🎨 Palette: [UX improvement] ContextSection 아코디언 접근성 개선 및 포커스 스타일 추가

.Jules/palette.md

@@ -1,3 +1,7 @@
 ## 2024-06-22 - Overview Stats 토글 버튼 키보드 접근성 개선
 **Learning:** `overview-stats` 컴포넌트의 설명 텍스트를 펼치거나 접는 `<button>` 요소에 키보드 포커스 스타일이 누락되어 있어, 키보드 내비게이션 사용자에게 현재 포커스 위치를 명확히 보여주지 못했습니다. `hover` 스타일은 있었으나 `focus-visible` 처리가 없어 접근성 결함이 있었습니다.
-**Action:** Tailwind CSS의 `focus-visible` 관련 유틸리티 클래스(`focus-visible:outline-none`, `focus-visible:ring-2`, `focus-visible:ring-ring`, `rounded-sm`)를 추가하여 탭(Tab) 키 이동 시 포커스 링이 보이도록 수정했습니다. 앞으로 대화형 컴포넌트를 설계할 때는 항상 키보드 접근성(focus states)을 염두에 두고 작업해야 합니다.
+**Action:** Tailwind CSS의 `focus-visible` 관련 유틸리티 클래스(`focus-visible:outline-none`, `focus-visible:ring-2`, `focus-visible:ring-ring`, `rounded-sm`)를 추가하여 탭(Tab) 키 이동 시 포커스 링이 보이도록 수정했습니다. 앞으로 대화형 컴포넌트를 설계할 때는 항상 키보드 접근성(focus states)을 염두에 두고 작업해야 합니다.
+
+## 2024-07-10 - 접을 수 있는 영역(Collapsible Region) 접근성 개선
+**Learning:** `ContextSection` 컴포넌트와 같이 아코디언 형태의 접을 수 있는 영역은 스크린 리더가 컨텐츠의 상태를 올바르게 인식하고 읽어주기 위해 토글 버튼과 컨텐츠 컨테이너 간의 명확한 ARIA 연결이 필요합니다. React의 `useId()` 훅을 사용하여 `aria-controls`, `id`, `aria-labelledby`를 동적으로 생성해 서로 연결하면 안정적입니다. 또한, 컨텐츠 영역에는 `role="region"`이 반드시 필요하다는 점을 확인했습니다.
+**Action:** 향후 접을 수 있는 컴포넌트(Collapsible Region)를 만들거나 수정할 때는 항상 `useId()`를 사용하여 토글 버튼(`aria-controls`)과 컨텐츠 컨테이너(`id`, `role="region"`, `aria-labelledby`)를 동적으로 연결하도록 합니다. 추가로 키보드 네비게이션 사용자를 위한 명확한 포커스 링(`focus-visible` 관련 클래스 적용) 처리도 잊지 말아야 합니다.

packages/web/package.json

@@ -43,7 +43,9 @@
   "devDependencies": {
     "@tailwindcss/postcss": "^4.2.2",
     "@testing-library/dom": "^10.4.1",
+    "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
     "@types/bcryptjs": "^2",
     "@types/node": "^20",
     "@types/react": "^19",

packages/web/src/components/dashboard/reports/context-section.test.tsx

@@ -0,0 +1,51 @@
+/** @vitest-environment jsdom */
+import React from 'react'
+import { afterEach, describe, expect, it } from 'vitest'
+import { render, screen, cleanup } from '@testing-library/react'
+import '@testing-library/jest-dom/vitest'
+import userEvent from '@testing-library/user-event'
+import { ContextSection } from './context-section'
+
+describe('ContextSection', () => {
+  afterEach(() => {
+    cleanup()
+  })
+
+  it('renders title and toggles content', async () => {
+    const user = userEvent.setup()
+    render(
+      <ContextSection title="Test Title">
+        <div data-testid="test-content">Content</div>
+      </ContextSection>
+    )
+
+    // Initially closed
+    expect(screen.getByRole('button', { name: 'Test Title' })).toHaveAttribute('aria-expanded', 'false')
+    expect(screen.queryByTestId('test-content')).not.toBeInTheDocument()
+
+    // Click to open
+    await user.click(screen.getByRole('button', { name: 'Test Title' }))
+    expect(screen.getByRole('button', { name: 'Test Title' })).toHaveAttribute('aria-expanded', 'true')
+
+    const region = screen.getByRole('region', { name: 'Test Title' })
+    expect(region).toBeInTheDocument()
+    expect(screen.getByTestId('test-content')).toBeInTheDocument()
+
+    // Click to close
+    await user.click(screen.getByRole('button', { name: 'Test Title' }))
+    expect(screen.getByRole('button', { name: 'Test Title' })).toHaveAttribute('aria-expanded', 'false')
+    expect(screen.queryByTestId('test-content')).not.toBeInTheDocument()
+  })
+
+  it('renders open by default if defaultOpen is true', () => {
+    render(
+      <ContextSection title="Test Title" defaultOpen>
+        <div data-testid="test-content">Content</div>
+      </ContextSection>
+    )
+
+    expect(screen.getByRole('button', { name: 'Test Title' })).toHaveAttribute('aria-expanded', 'true')
+    expect(screen.getByTestId('test-content')).toBeInTheDocument()
+    expect(screen.getByRole('region', { name: 'Test Title' })).toBeInTheDocument()
+  })
+})

packages/web/src/components/dashboard/reports/context-section.tsx

@@ -1,6 +1,6 @@
 'use client'
 
-import { useState, type ReactNode } from 'react'
+import React, { useState, useId, type ReactNode } from 'react'
 import { ChevronDown, ChevronUp } from 'lucide-react'
 import { cn } from '@/lib/utils'
 
@@ -12,17 +12,22 @@ interface ContextSectionProps {
 
 export function ContextSection({ title, children, defaultOpen = false }: ContextSectionProps) {
   const [open, setOpen] = useState(defaultOpen)
+  const id = useId()
+  const buttonId = `context-section-btn-${id}`
+  const contentId = `context-section-content-${id}`
 
   return (
     <div className="rounded-xl bg-card ring-1 ring-foreground/10 overflow-hidden">
       <button
         type="button"
+        id={buttonId}
         onClick={() => setOpen((v) => !v)}
         className={cn(
           'w-full flex items-center justify-between px-4 py-3 text-left',
-          'hover:bg-card-elevated transition-colors',
+          'hover:bg-card-elevated transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
         )}
         aria-expanded={open}
+        aria-controls={contentId}
       >
         <h2 className="text-base font-medium">{title}</h2>
         {open ? (
@@ -32,7 +37,12 @@ export function ContextSection({ title, children, defaultOpen = false }: Context
         )}
       </button>
       {open && (
-        <div className="px-4 pb-4 pt-1">
+        <div
+          id={contentId}
+          role="region"
+          aria-labelledby={buttonId}
+          className="px-4 pb-4 pt-1"
+        >
           {children}
         </div>
       )}