🎨 Palette: SettingsLayout 비활성화 버튼 접근성 툴팁 개선

docs/product-technical-gap-baseline.md

@@ -3,7 +3,7 @@
 **Baseline version:** 1.2
 **Observed on:** 2026-08-26 (Asia/Seoul)
 **Observed protected branch (current scan; row Base-SHA values remain historical):** `develop@e5e99b4e3bb081b92c602358878856536030e2ca`
-**Observed product version:** `0.14.4`  
+**Observed product version:** `0.14.4`
 **Canonical completion issue:** [#1428](https://github.com/ContextualWisdomLab/naruon/issues/1428)
 
 **Inventory observation:** the 106-PR open surface below is a fresh live

frontend/src/components/NetworkGraph.test.tsx

@@ -108,7 +108,7 @@ describe("NetworkGraph", () => {
     expect(Network).not.toHaveBeenCalled();
   });
 
-  it("describes the unavailable first-relationship action programmatically", async () => {
+  it("keeps the unavailable first-relationship reason visible and the guarded action focusable", async () => {
     const fetchMock = vi.fn(() =>
       Promise.resolve(
         jsonResponse({
@@ -123,22 +123,22 @@ describe("NetworkGraph", () => {
     await flushAsyncWork();
 
     const mountedContainer = getMountedContainer();
-    const wrapper = mountedContainer.querySelector('span[tabindex="0"]');
-    const button = mountedContainer.querySelector('button[disabled]');
-    const descriptionId = wrapper?.getAttribute("aria-describedby");
-
-    expect(wrapper).toBeInstanceOf(HTMLSpanElement);
-    expect(wrapper?.className).toContain("cursor-not-allowed");
-    expect(wrapper?.getAttribute("title")).toBe("표시할 관계 데이터가 없습니다.");
-    expect(wrapper?.className).toContain("focus-visible:ring-2");
-    expect(descriptionId).toBeTruthy();
-    expect(document.getElementById(descriptionId ?? "")?.textContent).toBe(
-      "표시할 관계 데이터가 없습니다.",
-    );
+    const button = mountedContainer.querySelector('button[aria-disabled="true"]');
+    const descriptionId = button?.getAttribute("aria-describedby");
+
     expect(button).toBeInstanceOf(HTMLButtonElement);
-    expect((button as HTMLButtonElement).disabled).toBe(true);
-    expect(button?.className).toContain("disabled:cursor-not-allowed");
-    expect(button?.className).toContain("pointer-events-none");
+    expect((button as HTMLButtonElement).disabled).toBe(false);
+    expect(button?.className).toContain("aria-disabled:cursor-not-allowed");
+    expect(button?.className).toContain("focus-visible:ring-2");
+    expect(descriptionId).toBeTruthy();
+    const reason = document.getElementById(descriptionId ?? "");
+    expect(reason?.className).not.toContain("sr-only");
+    expect(reason?.textContent).toBe("연결된 관계가 생기면 첫 관계를 확인할 수 있습니다.");
+
+    (button as HTMLButtonElement).focus();
+    expect(document.activeElement).toBe(button);
+    button?.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true }));
+    expect(mountedContainer.textContent).not.toContain("첫 관계를 선택했습니다.");
   });
 
   it("announces graph loading failures as a polite alert", async () => {

frontend/src/components/NetworkGraph.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { useEffect, useId, useMemo, useRef, useState } from 'react';
+import { useEffect, useId, useMemo, useRef, useState, type MouseEvent } from 'react';
 import { Network } from 'vis-network';
 
 interface Node {
@@ -322,8 +322,11 @@ export default function NetworkGraph() {
     networkRef.current?.fit?.({ nodes: [node.id], animation: false });
   };
 
-  const handleSelectFirstRelationship = () => {
-    if (!firstEdge) return;
+  const handleSelectFirstRelationship = (event: MouseEvent<HTMLButtonElement>) => {
+    if (!firstEdge) {
+      event.preventDefault();
+      return;
+    }
     selectRelationship(firstEdge, '첫 관계를 선택했습니다.');
   };
 
@@ -390,30 +393,22 @@ export default function NetworkGraph() {
           </p>
         </div>
         <div className="mt-3 flex flex-wrap gap-2">
-          <span
-            tabIndex={!firstEdge ? 0 : undefined}
-            aria-describedby={!firstEdge ? unavailableRelationshipDescriptionId : undefined}
-            title={!firstEdge ? "표시할 관계 데이터가 없습니다." : undefined}
-            className={
-              !firstEdge
-                ? "cursor-not-allowed rounded-md focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-2"
-                : undefined
-            }
-          >
-            {!firstEdge && (
-              <span id={unavailableRelationshipDescriptionId} className="sr-only">
-                표시할 관계 데이터가 없습니다.
-              </span>
-            )}
+          <div className="flex max-w-xs flex-col items-start gap-2">
             <button
               type="button"
               onClick={handleSelectFirstRelationship}
-              disabled={!firstEdge}
-              className={`rounded-md border border-primary/25 bg-background px-3 py-2 text-xs font-bold text-primary transition hover:bg-primary/10 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary disabled:cursor-not-allowed disabled:opacity-50 ${!firstEdge ? "pointer-events-none" : ""}`}
+              aria-disabled={!firstEdge}
+              aria-describedby={!firstEdge ? unavailableRelationshipDescriptionId : undefined}
+              className="rounded-md border border-primary/25 bg-background px-3 py-2 text-xs font-bold text-primary transition hover:bg-primary/10 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-2 aria-disabled:cursor-not-allowed aria-disabled:opacity-50"
             >
               첫 관계 보기
             </button>
-          </span>
+            {!firstEdge && (
+              <p id={unavailableRelationshipDescriptionId} className="text-xs font-semibold leading-5 text-muted-foreground">
+                연결된 관계가 생기면 첫 관계를 확인할 수 있습니다.
+              </p>
+            )}
+          </div>
           <button
             type="button"
             onClick={handleZoomGraph}

frontend/src/components/SettingsLayout.test.tsx

@@ -46,8 +46,12 @@ function jsonResponse(body: unknown) {
 describe("SettingsLayout", () => {
   let root: Root | null = null;
   let container: HTMLDivElement | null = null;
+  let failAccountConfigLoad = false;
+  let failAccountConfigSave = false;
 
   beforeEach(() => {
+    failAccountConfigLoad = false;
+    failAccountConfigSave = false;
     oidcMocks.getOidcBrowserConfig.mockReturnValue({
       issuerUrl: "https://login.example.com/realms/naruon",
       clientId: "naruon-web",
@@ -246,6 +250,9 @@ describe("SettingsLayout", () => {
           ]);
         }
         if (String(input) === "/api/accounts/config" && init?.method === "PUT") {
+          if (failAccountConfigSave) {
+            return Promise.reject(new Error("계정 설정 저장 실패"));
+          }
           const body = JSON.parse(String(init.body));
           return jsonResponse({
             user_id: "default",
@@ -267,6 +274,9 @@ describe("SettingsLayout", () => {
           });
         }
         if (String(input) === "/api/accounts/config") {
+          if (failAccountConfigLoad) {
+            return Promise.reject(new Error("계정 설정 조회 실패"));
+          }
           return jsonResponse({
             user_id: "default",
             smtp_server: "smtp.example.com",
@@ -491,6 +501,54 @@ describe("SettingsLayout", () => {
     });
   });
 
+  it("announces session loading before enabling logout", async () => {
+    oidcMocks.getOidcBrowserConfig.mockReturnValue(null);
+    const defaultFetch = vi.mocked(fetch);
+    vi.stubGlobal("fetch", vi.fn((input: RequestInfo | URL, init?: RequestInit) => {
+      if (String(input) === "/auth/session") {
+        return new Promise<Response>(() => undefined);
+      }
+      return defaultFetch(input, init);
+    }));
+
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    root = createRoot(container);
+
+    await act(async () => {
+      root?.render(<SettingsLayout />);
+      await Promise.resolve();
+    });
+
+    const developerTab = Array.from(container.querySelectorAll("button")).find(
+      (button) => button.textContent === "개발자",
+    );
+    await act(async () => {
+      developerTab?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+      await Promise.resolve();
+    });
+
+    const logoutButton = Array.from(container.querySelectorAll("button")).find((button) => button.textContent === "로그아웃");
+    const loginButton = Array.from(container.querySelectorAll("button")).find((button) => button.textContent === "OIDC 로그인");
+    const loginReason = container.querySelector('#oidc-login-availability');
+    expect(loginButton?.getAttribute("aria-disabled")).toBe("true");
+    expect(loginReason?.className).not.toContain("sr-only");
+    expect(loginReason?.textContent).toBe("OIDC 로그인을 사용하려면 관리자에게 OIDC 설정을 요청하세요.");
+    expect(logoutButton?.getAttribute("aria-disabled")).toBe("true");
+    expect(logoutButton?.getAttribute("aria-describedby")).toBe("oidc-logout-availability");
+    const logoutReason = container.querySelector('#oidc-logout-availability');
+    expect(logoutReason?.className).not.toContain("sr-only");
+    expect(logoutReason?.textContent).toBe("로그인 세션을 확인하는 중입니다. 잠시만 기다려 주세요.");
+    logoutButton?.focus();
+    expect(document.activeElement).toBe(logoutButton);
+
+    await act(async () => {
+      logoutButton?.click();
+      await Promise.resolve();
+    });
+    expect(oidcMocks.clearOidcSession).not.toHaveBeenCalled();
+  });
+
   it("loads and saves source-backed mail account settings without public identity headers or secret replay", async () => {
     container = document.createElement("div");
     document.body.appendChild(container);
@@ -598,6 +656,64 @@ describe("SettingsLayout", () => {
     expect(container.textContent).toContain("계정 설정을 저장했습니다");
   });
 
+  it("announces an account configuration load error instead of a loading state", async () => {
+    failAccountConfigLoad = true;
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    root = createRoot(container);
+
+    await act(async () => {
+      root?.render(<SettingsLayout />);
+      await Promise.resolve();
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+
+    const accountButton = Array.from(container.querySelectorAll("button")).find((button) => button.textContent === "연결 계정");
+    await act(async () => {
+      accountButton?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+      await Promise.resolve();
+    });
+
+    const saveButton = Array.from(container.querySelectorAll("button")).find((button) => button.textContent === "계정 설정 저장");
+    expect(saveButton?.getAttribute("aria-describedby")).toBe("account-save-availability");
+    const accountReason = container.querySelector('#account-save-availability');
+    expect(accountReason?.className).not.toContain("sr-only");
+    expect(accountReason?.textContent).toBe("계정 설정을 불러오지 못했습니다. 잠시 후 다시 시도하거나 관리자에게 문의하세요.");
+    expect(container.textContent).not.toContain("계정 설정을 불러오는 중입니다. 잠시 후 다시 시도하세요.");
+  });
+
+  it("keeps account saving available after a save failure", async () => {
+    failAccountConfigSave = true;
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    root = createRoot(container);
+
+    await act(async () => {
+      root?.render(<SettingsLayout />);
+      await Promise.resolve();
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+
+    const accountButton = Array.from(container.querySelectorAll("button")).find((button) => button.textContent === "연결 계정");
+    await act(async () => {
+      accountButton?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+      await Promise.resolve();
+    });
+    const accountForm = container.querySelector('form');
+    await act(async () => {
+      accountForm?.dispatchEvent(new Event("submit", { bubbles: true, cancelable: true }));
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+
+    const updatedSaveButton = Array.from(container.querySelectorAll("button")).find((button) => button.textContent === "계정 설정 저장");
+    expect(container.textContent).toContain("API request failed");
+    expect(updatedSaveButton?.getAttribute("aria-disabled")).toBeNull();
+    expect(updatedSaveButton?.getAttribute("aria-describedby")).toBeNull();
+  });
+
   it("loads and saves AI model registry entries without public identity headers or secret replay", async () => {
     container = document.createElement("div");
     document.body.appendChild(container);