fix(a11y): expose async button busy states

docs/doctoring/async-button-busy-state.md

@@ -0,0 +1,25 @@
+# Async button busy-state accessibility
+
+## Decision
+
+Naruon exposes `aria-busy=true` only while an action control is actively processing its asynchronous operation. The existing `disabled` behavior remains responsible for preventing duplicate activation; `aria-busy` communicates the processing state to the accessibility API rather than replacing the disabled-state contract.
+
+The bounded change applies to the project evidence-review action, repository document actions, and duplicate-thread intent action. It does not claim whole-product accessibility conformance or imply that every statically disabled control is busy.
+
+## Evidence boundary
+
+WAI-ARIA defines `aria-busy` as a state indicating that an element is being modified and that assistive technologies can defer exposing intermediate changes until the operation is complete. The attribute is defined for all elements in the base markup and defaults to `false`. This supports binding `aria-busy` to the same boolean state that represents the in-flight asynchronous action, while leaving ordinary unavailable controls unmarked as busy.
+
+## Verification
+
+Merge readiness is determined only from the unchanged current PR head after repository CI, security, coverage, review, and protected-branch requirements pass. The accessibility attribute itself is not a substitute for rendered assistive-technology testing across supported environments.
+
+## Reference — APA 7th
+
+World Wide Web Consortium. (2026, June 4). *Accessible Rich Internet Applications (WAI-ARIA) 1.3* (Working Draft). https://www.w3.org/TR/2026/WD-wai-aria-1.3-20260604/
+
+## Action identity
+
+A shared loading lock may disable sibling document actions to prevent conflicting writes, but it must not announce every sibling as the operation that is currently processing. Naruon therefore records the initiating document action separately from the shared lock. Only the initiating upload, reparse, embedding-regeneration, HWP-conversion, or WebDAV-materialization button exposes `aria-busy=true`; disabled siblings remain `aria-busy=false`.
+
+The focused server-rendered regression exercises the real button group and fails if a shared boolean again marks every document action busy. Stable `data-document-action` identifiers exist only to bind rendered accessibility evidence to the initiating operation; they do not authorize or execute an action.

frontend/src/components/DataLayout.tsx

@@ -18,6 +18,8 @@ import {
   UniqueThreadStatus,
   EmailImportStatus,
   DocumentActionStatus,
+  ActiveDocumentAction,
+  DocumentOperation,
   DataSurfaceStatus,
   DataEvidenceSnapshotResponse,
   DataQualitySurfaceResponse,
@@ -65,6 +67,7 @@ export function DataLayout() {
   const [emailImportResult, setEmailImportResult] = useState<EmailFileImportResponse | null>(null);
   const [emailImportFiles, setEmailImportFiles] = useState<File[]>([]);
   const [documentActionStatus, setDocumentActionStatus] = useState<DocumentActionStatus>('idle');
+  const [activeDocumentAction, setActiveDocumentAction] = useState<ActiveDocumentAction | null>(null);
   const [documentActionResult, setDocumentActionResult] = useState<DataDocumentActionResponse | null>(null);
   const [documentUploadFiles, setDocumentUploadFiles] = useState<File[]>([]);
   const [dataSurfaceStatus, setDataSurfaceStatus] = useState<DataSurfaceStatus>('loading');
@@ -239,14 +242,16 @@ export function DataLayout() {
       return;
     }
 
+    const documentType = getDocumentTypeForFile(file);
+    if (!isTextDocumentUploadType(documentType)) {
+      setDocumentActionStatus('error');
+      return;
+    }
+
+    setActiveDocumentAction('upload');
     setDocumentActionStatus('loading');
     setDocumentActionResult(null);
     try {
-      const documentType = getDocumentTypeForFile(file);
-      if (!isTextDocumentUploadType(documentType)) {
-        setDocumentActionStatus('error');
-        return;
-      }
       const documentContent = await file.text();
       const result = await apiClient.post<DataDocumentActionResponse>(
         '/api/data/documents',
@@ -263,11 +268,13 @@ export function DataLayout() {
     } catch (error: unknown) {
       const status = getApiErrorStatus(error);
       setDocumentActionStatus(status === 401 || status === 403 ? 'auth' : 'error');
+    } finally {
+      setActiveDocumentAction(null);
     }
   }, [documentUploadFiles, loadDataQualitySurface]);
 
   const requestDocumentAction = useCallback(async (
-    action: 'reparse' | 'embedding-regeneration-intent' | 'hwp-conversion-intent' | 'webdav-materialization-intent',
+    action: DocumentOperation,
   ) => {
     const asset = dataQualitySurface?.repository_assets.find((candidate) => (
       candidate.asset_key === selectedRepositoryAssetKey
@@ -284,6 +291,7 @@ export function DataLayout() {
       return;
     }
 
+    setActiveDocumentAction(action);
     setDocumentActionStatus('loading');
     setDocumentActionResult(null);
     try {
@@ -300,6 +308,8 @@ export function DataLayout() {
     } catch (error: unknown) {
       const status = getApiErrorStatus(error);
       setDocumentActionStatus(status === 401 || status === 403 ? 'auth' : 'error');
+    } finally {
+      setActiveDocumentAction(null);
     }
   }, [
     dataQualitySurface,
@@ -441,6 +451,7 @@ export function DataLayout() {
               handleDocumentFileChange={handleDocumentFileChange}
               requestDocumentUpload={requestDocumentUpload}
               isDocumentActionLoading={isDocumentActionLoading}
+              activeDocumentAction={activeDocumentAction}
               documentUploadFiles={documentUploadFiles}
               documentActionStatus={documentActionStatus}
               documentActionResult={documentActionResult}

frontend/src/components/ProjectsLayout.tsx

@@ -969,6 +969,7 @@ export function ProjectsLayout() {
                               type="button"
                               onClick={handleMarkEvidenceReviewed}
                               disabled={correctionSubmitting || evidenceLoading}
+                              aria-busy={correctionSubmitting || evidenceLoading}
                               className="mt-3 min-h-9 w-full rounded-md bg-primary px-3 text-xs font-bold text-primary-foreground hover:bg-primary/90 disabled:cursor-not-allowed disabled:bg-secondary disabled:text-muted-foreground"
                             >
                               {correctionSubmitting ? '검토 저장 중' : '문단 근거 검토 저장'}

frontend/src/components/data-layout/DocumentRepositoryTab.busy-state.test.tsx

@@ -0,0 +1,97 @@
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+
+import { DocumentRepositoryTab } from './DocumentRepositoryTab';
+
+const workspaceDocument = {
+  asset_key: 'workspace-document-1',
+  asset_type: 'workspace_document',
+  display_name: '운영 계약.md',
+  source_label: '로컬 문서',
+  state_code: 'ready',
+  detail_text: '검토 가능한 문서 근거',
+  content_chars: 128,
+  captured_at: '2026-08-15T09:00:00+09:00',
+  evidence_source: 'workspace_document',
+  thread_key: 'thread-1',
+  provider_write_executed: false,
+};
+
+function renderRepository(activeDocumentAction: string | null) {
+  return renderToStaticMarkup(
+    <DocumentRepositoryTab
+      {...({
+        writebackStatus: 'idle',
+        writebackResult: null,
+        requestWebdavWritebackIntent: () => undefined,
+        isWritebackLoading: false,
+        canRequestWebdavWriteback: true,
+        selectedWebdavAccount: {
+          source_id: 'webdav-1',
+          display_label: '업무 문서',
+          writeback_enabled: true,
+        },
+        isWebdavSourceLoading: false,
+        setSelectedWebdavSourceId: () => undefined,
+        uniqueThreadStatus: 'idle',
+        uniqueThreadResult: null,
+        requestUniqueThreadIntent: () => undefined,
+        isUniqueThreadLoading: false,
+        connectorEvents: [],
+        dataSurfaceStatus: 'ready',
+        dataQualitySurface: null,
+        embeddingStage: null,
+        emailRepository: null,
+        attachmentRepository: null,
+        handleEmailImportFileChange: () => undefined,
+        requestEmailFileImport: () => undefined,
+        isEmailImportLoading: false,
+        emailImportFiles: [],
+        emailImportStatus: 'idle',
+        emailImportResult: null,
+        handleDocumentFileChange: () => undefined,
+        requestDocumentUpload: () => undefined,
+        isDocumentActionLoading: true,
+        activeDocumentAction,
+        documentUploadFiles: [],
+        documentActionStatus: 'loading',
+        documentActionResult: null,
+        webdavAccountStatus: 'ready',
+        webdavAccounts: [{
+          source_id: 'webdav-1',
+          display_label: '업무 문서',
+          writeback_enabled: true,
+        }],
+        webdavAccountMap: new Map(),
+        projectFolders: [],
+        selectedRepositoryAssetKey: workspaceDocument.asset_key,
+        setSelectedRepositoryAssetKey: () => undefined,
+        repositoryAssets: [workspaceDocument],
+        selectedWorkspaceDocument: workspaceDocument,
+        requestDocumentAction: () => undefined,
+      } as never)}
+    />,
+  );
+}
+
+function getActionButtonTag(markup: string, action: string) {
+  const match = markup.match(
+    new RegExp(`<button[^>]*data-document-action="${action}"[^>]*>`),
+  );
+  if (!match) {
+    throw new Error(`missing rendered button for ${action}`);
+  }
+  return match[0];
+}
+
+describe('DocumentRepositoryTab action busy identity', () => {
+  it('marks only the initiating document action as busy', () => {
+    const markup = renderRepository('reparse');
+
+    expect(getActionButtonTag(markup, 'reparse')).toContain('aria-busy="true"');
+    expect(getActionButtonTag(markup, 'embedding-regeneration-intent')).toContain('aria-busy="false"');
+    expect(getActionButtonTag(markup, 'hwp-conversion-intent')).toContain('aria-busy="false"');
+    expect(getActionButtonTag(markup, 'webdav-materialization-intent')).toContain('aria-busy="false"');
+    expect(getActionButtonTag(markup, 'upload')).toContain('aria-busy="false"');
+  });
+});

frontend/src/components/data-layout/DocumentRepositoryTab.tsx

@@ -6,6 +6,8 @@ import {
   DataQualitySurfaceResponse,
   EmailImportStatus,
   DocumentActionStatus,
+  ActiveDocumentAction,
+  DocumentOperation,
   EmailFileImportResponse,
   DataDocumentActionResponse,
   WebdavAccountStatus,
@@ -53,6 +55,7 @@ interface DocumentRepositoryTabProps {
   handleDocumentFileChange: (event: ChangeEvent<HTMLInputElement>) => void;
   requestDocumentUpload: () => void;
   isDocumentActionLoading: boolean;
+  activeDocumentAction: ActiveDocumentAction | null;
   documentUploadFiles: File[];
   documentActionStatus: DocumentActionStatus;
   documentActionResult: DataDocumentActionResponse | null;
@@ -64,7 +67,7 @@ interface DocumentRepositoryTabProps {
   setSelectedRepositoryAssetKey: (key: string | null) => void;
   repositoryAssets: any[];
   selectedWorkspaceDocument: any;
-  requestDocumentAction: (action: 'reparse' | 'embedding-regeneration-intent' | 'hwp-conversion-intent' | 'webdav-materialization-intent') => void;
+  requestDocumentAction: (action: DocumentOperation) => void;
 }
 
 export function DocumentRepositoryTab({
@@ -82,6 +85,7 @@ export function DocumentRepositoryTab({
   handleDocumentFileChange,
   requestDocumentUpload,
   isDocumentActionLoading,
+  activeDocumentAction,
   documentUploadFiles,
   documentActionStatus,
   documentActionResult,
@@ -190,8 +194,9 @@ return (
                       <button
                         type="button"
                         onClick={() => void requestDocumentUpload()}
+                        data-document-action="upload"
                         disabled={isDocumentActionLoading || documentUploadFiles.length === 0}
-                        aria-busy={isDocumentActionLoading}
+                        aria-busy={activeDocumentAction === 'upload'}
                         className="inline-flex min-h-9 items-center justify-center gap-2 rounded-lg bg-primary px-3 py-2 text-xs font-bold text-primary-foreground hover:bg-primary/90 disabled:cursor-not-allowed disabled:opacity-60 sm:w-fit"
                       >
                         <Upload className="size-4" />
@@ -374,7 +379,9 @@ return (
                       <button
                         type="button"
                         onClick={() => void requestDocumentAction('reparse')}
+                        data-document-action="reparse"
                         disabled={isDocumentActionLoading}
+                        aria-busy={activeDocumentAction === 'reparse'}
                         className="inline-flex min-h-9 items-center justify-center gap-2 rounded-lg border border-border bg-background px-3 py-2 text-xs font-bold text-foreground hover:bg-secondary disabled:cursor-wait disabled:opacity-60"
                       >
                         <RefreshCw className="size-4" />
@@ -383,7 +390,9 @@ return (
                       <button
                         type="button"
                         onClick={() => void requestDocumentAction('embedding-regeneration-intent')}
+                        data-document-action="embedding-regeneration-intent"
                         disabled={isDocumentActionLoading}
+                        aria-busy={activeDocumentAction === 'embedding-regeneration-intent'}
                         className="inline-flex min-h-9 items-center justify-center gap-2 rounded-lg border border-border bg-background px-3 py-2 text-xs font-bold text-foreground hover:bg-secondary disabled:cursor-wait disabled:opacity-60"
                       >
                         <Database className="size-4" />
@@ -392,7 +401,9 @@ return (
                       <button
                         type="button"
                         onClick={() => void requestDocumentAction('hwp-conversion-intent')}
+                        data-document-action="hwp-conversion-intent"
                         disabled={isDocumentActionLoading}
+                        aria-busy={activeDocumentAction === 'hwp-conversion-intent'}
                         className="inline-flex min-h-9 items-center justify-center gap-2 rounded-lg border border-border bg-background px-3 py-2 text-xs font-bold text-foreground hover:bg-secondary disabled:cursor-wait disabled:opacity-60"
                       >
                         <FileText className="size-4" />
@@ -401,8 +412,9 @@ return (
                       <button
                         type="button"
                         onClick={() => void requestDocumentAction('webdav-materialization-intent')}
+                        data-document-action="webdav-materialization-intent"
                         disabled={isDocumentActionLoading || !selectedWebdavAccount || selectedWorkspaceDocument.state_code !== 'ready'}
-                        aria-busy={isDocumentActionLoading}
+                        aria-busy={activeDocumentAction === 'webdav-materialization-intent'}
                         className="inline-flex min-h-9 items-center justify-center gap-2 rounded-lg bg-primary px-3 py-2 text-xs font-bold text-primary-foreground hover:bg-primary/90 disabled:cursor-not-allowed disabled:opacity-60"
                       >
                         <Server className="size-4" />
@@ -518,6 +530,7 @@ return (
                     type="button"
                     onClick={() => void requestUniqueThreadIntent()}
                     disabled={isUniqueThreadLoading}
+                    aria-busy={isUniqueThreadLoading}
                     className="w-full whitespace-nowrap rounded-xl bg-primary px-4 py-2 text-sm font-bold text-primary-foreground hover:bg-primary/90 disabled:cursor-wait disabled:opacity-60 sm:w-auto"
                   >
                     중복 메일 스레드 의도 점검

frontend/src/components/data-layout/types.ts

@@ -43,6 +43,8 @@ export type UniqueThreadIntentResponse = {
 export type UniqueThreadStatus = 'idle' | 'loading' | 'success' | 'auth' | 'error';
 export type EmailImportStatus = 'idle' | 'loading' | 'success' | 'auth' | 'error';
 export type DocumentActionStatus = 'idle' | 'loading' | 'success' | 'auth' | 'error';
+export type DocumentOperation = 'reparse' | 'embedding-regeneration-intent' | 'hwp-conversion-intent' | 'webdav-materialization-intent';
+export type ActiveDocumentAction = 'upload' | DocumentOperation;
 
 export type DataSurfaceStatus = 'loading' | 'ready' | 'error';