eslint-plugin-aria-state-validator 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 comento
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ko.md

@@ -0,0 +1,382 @@
+# eslint-plugin-aria-state-validator
+
+ARIA 접근성을 위한 포괄적인 ESLint 플러그인:
+
+- **동적 상태 검증**: ARIA 상태 속성이 컴포넌트 상태와 올바르게 연결되었는지 검증
+- **정적 ARIA 검증**: 정적 ARIA 속성의 정확성 검증 (철자, 값, 충돌)
+
+빌드 타임에 런타임 및 정적 접근성 오류를 미리 감지합니다.
+
+## 문제 제기: 정적 분석의 '런타임 공백'
+
+`eslint-plugin-jsx-a11y` 같은 기존 접근성 도구들은 ARIA 속성의 문법적 정확성(예: `aria-expanded`가 `'true'` 또는 `'false'`를 사용하는지)은 검증하지만, 이 속성들이 컴포넌트의 JavaScript 상태와 올바르게 연결되어 런타임에 동적으로 업데이트되는지는 **검증할 수 없습니다**.
+
+### 발생하는 문제:
+
+- 토글 버튼의 `aria-expanded="false"`가 하드코딩되어 열려도 변경되지 않음
+- ARIA 속성에 Boolean 값을 직접 바인딩: `aria-expanded={isOpen}` (오류 - 문자열이어야 함)
+- 인터랙티브 요소의 정적 ARIA 상태
+- 스크린 리더 사용자에게 부정확한 정보 전달
+
+## 핵심 컨셉: 상태 의존 ARIA 검증
+
+이 플러그인은 AST(추상 구문 트리) 분석을 통해 ARIA 상태 속성이 컴포넌트 상태(State/Props)와 논리적으로 연결되어 런타임에 업데이트될 것인지 **정적으로 검증**합니다.
+
+### 차별점
+
+단순 문법 검사를 넘어 컴포넌트의 **동적 동작**을 추론하여, 런타임에서만 발견되던 접근성 오류를 빌드/CI 단계에서 선제적으로 포착합니다.
+
+## 설치
+
+```bash
+npm install --save-dev eslint-plugin-aria-state-validator
+```
+
+## 사용법
+
+### ESLint Flat Config (ESLint 9+)
+
+```javascript
+// eslint.config.js
+import ariaStateValidator from "eslint-plugin-aria-state-validator";
+
+export default [
+  {
+    plugins: {
+      "aria-state-validator": ariaStateValidator,
+    },
+    rules: {
+      "aria-state-validator/state-dependent-aria-validator": "warn",
+      "aria-state-validator/static-aria-validator": "warn",
+    },
+  },
+];
+```
+
+### Legacy ESLintRC Config
+
+```json
+{
+  "plugins": ["aria-state-validator"],
+  "rules": {
+    "aria-state-validator/state-dependent-aria-validator": "warn",
+    "aria-state-validator/static-aria-validator": "warn"
+  }
+}
+```
+
+### 설정 프리셋
+
+```javascript
+// 권장 설정 (경고)
+...ariaStateValidator.configs.recommended
+
+// 엄격한 설정 (에러)
+...ariaStateValidator.configs.strict
+
+// 동적 검증만
+...ariaStateValidator.configs['dynamic-only']
+
+// 정적 검증만
+...ariaStateValidator.configs['static-only']
+```
+
+## 두 가지 규칙으로 포괄적인 ARIA 검증
+
+이 플러그인은 두 가지 보완적인 규칙을 제공합니다:
+
+### 규칙 1: `state-dependent-aria-validator` (동적 상태 검증)
+
+ARIA **상태** 속성이 컴포넌트 상태와 올바르게 연결되어 동적으로 업데이트되는지 검증합니다.
+
+### 규칙 2: `static-aria-validator` (정적 ARIA 검증)
+
+사용된 ARIA 속성의 **정확성**을 검증합니다:
+
+- 유효한 ARIA 속성 이름 (오타 감지)
+- Boolean 및 Enum ARIA 속성의 올바른 값
+- 충돌하는 ARIA 속성 감지
+- 네이티브 HTML 요소의 중복 role 감지
+
+**참고:** 이 플러그인은 ARIA 속성을 **어떻게** 사용하는지를 검증하며, **사용 여부**를 강제하지는 않습니다. 접근성 기능의 존재를 강제하려면 [eslint-plugin-jsx-a11y](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y)를 사용하세요.
+
+## 기능 및 검증 패턴
+
+## 동적 상태 검증 패턴
+
+### 1. Boolean 값 직접 바인딩 감지
+
+**감지 내용:** ARIA 속성에 Boolean 값을 직접 바인딩
+
+```jsx
+// ❌ 오류: Boolean 값 직접 바인딩
+<button aria-expanded={isOpen}>토글</button>
+
+// ✅ 올바름: 명시적 문자열 변환
+<button aria-expanded={isOpen ? 'true' : 'false'}>토글</button>
+```
+
+**자동 수정 가능:** `eslint --fix`가 자동으로 올바른 문자열 형식으로 변환합니다
+
+### 2. 정적 값 + 인터랙티브 핸들러 감지
+
+**감지 내용:** 이벤트 핸들러가 있는 요소의 정적 ARIA 상태 값
+
+```jsx
+// ❌ 오류: onClick이 있지만 aria-expanded가 정적
+<button onClick={handleClick} aria-expanded="false">
+  토글
+</button>
+
+// ✅ 올바름: 동적 상태 바인딩
+<button onClick={handleClick} aria-expanded={isOpen ? 'true' : 'false'}>
+  토글
+</button>
+```
+
+**스마트 자동 수정:** 핸들러에 상태 변수 참조가 있으면 (예: `() => setExpanded(!expanded)`), 플러그인이 자동으로 변수 이름을 추출하여 ARIA 속성에 바인딩합니다:
+
+```jsx
+// ❌ 자동 수정 전
+<div onClick={() => setExpanded(!expanded)} aria-expanded="false">
+  클릭하여 확장
+</div>
+
+// ✅ 자동 수정 후 (자동으로 'expanded' 변수 감지)
+<div onClick={() => setExpanded(!expanded)} aria-expanded={expanded ? 'true' : 'false'}>
+  클릭하여 확장
+</div>
+```
+
+### 3. 역할 기반 상태 연관성 검증
+
+**감지 내용:** 정적 ARIA 상태를 가진 인터랙티브 역할
+
+```jsx
+// ❌ 오류: role="button"인데 aria-pressed가 정적
+<div role="button" aria-pressed="false">버튼</div>
+
+// ✅ 올바름: 동적 상태 바인딩
+<div role="button" aria-pressed={isPressed ? 'true' : 'false'}>버튼</div>
+```
+
+---
+
+## 정적 ARIA 검증 패턴
+
+### 4. 유효하지 않은 ARIA 속성 감지
+
+**감지 내용:** ARIA 속성 이름의 오타
+
+```jsx
+// ❌ 오류: aria-label의 오타
+<button aria-labell="닫기">X</button>
+
+// ✅ 올바름: 올바른 철자
+<button aria-label="닫기">X</button>
+```
+
+### 5. 빈 필수 값
+
+**감지 내용:** 비어있지 않은 값이 필요한 ARIA 속성
+
+```jsx
+// ❌ 오류: aria-label이 비어있음
+<div aria-label="">내용</div>
+
+// ✅ 올바름: 비어있지 않은 값
+<div aria-label="설명">내용</div>
+```
+
+### 6. 유효하지 않은 Boolean 값
+
+**감지 내용:** 잘못된 boolean 형식 값
+
+```jsx
+// ❌ 오류: 유효하지 않은 boolean 값
+<div aria-hidden="yes">내용</div>
+<div aria-disabled="1">내용</div>
+
+// ✅ 올바름: "true" 또는 "false" 사용
+<div aria-hidden="true">내용</div>
+<div aria-disabled="false">내용</div>
+```
+
+### 7. 유효하지 않은 Enum 값
+
+**감지 내용:** Enum 타입 ARIA 속성의 유효하지 않은 값
+
+```jsx
+// ❌ 오류: 유효하지 않은 aria-live 값
+<div aria-live="loud">라이브 영역</div>
+
+// ✅ 올바름: 유효한 enum 값 사용
+<div aria-live="polite">라이브 영역</div>
+
+// 유효한 값: "off", "polite", "assertive"
+```
+
+### 8. 충돌하는 ARIA 속성
+
+**감지 내용:** aria-label과 aria-labelledby를 함께 사용
+
+```jsx
+// ❌ 오류: 두 속성 모두 존재 (aria-labelledby가 우선)
+<div aria-label="레이블" aria-labelledby="other-id">내용</div>
+
+// ✅ 올바름: 하나만 사용
+<div aria-labelledby="other-id">내용</div>
+```
+
+### 9. 중복 Role
+
+**감지 내용:** 네이티브 HTML 시맨틱과 일치하는 명시적 role
+
+```jsx
+// ❌ 오류: 중복 role
+<button role="button">클릭</button>
+<nav role="navigation">내비게이션</nav>
+<a href="#" role="link">링크</a>
+
+// ✅ 올바름: 네이티브 시맨틱 사용
+<button>클릭</button>
+<nav>내비게이션</nav>
+<a href="#">링크</a>
+```
+
+---
+
+## 지원하는 ARIA 속성 (동적 검증)
+
+플러그인이 검증하는 동적 ARIA 상태 속성:
+
+- `aria-expanded` - 토글 버튼, 확장 가능한 요소
+- `aria-selected` - 탭, 선택 가능한 옵션
+- `aria-checked` - 체크박스, 라디오 버튼
+- `aria-pressed` - 토글 버튼
+- `aria-hidden` - 동적으로 표시/숨김되는 요소
+- `aria-disabled` - 동적으로 활성화/비활성화되는 요소
+- `aria-modal` - 다이얼로그, 모달
+- `aria-current` - 현재 활성 항목 표시
+
+## 지원하는 인터랙티브 역할
+
+다음 역할을 가진 요소는 동적 ARIA 상태가 필요합니다:
+
+- `button`, `tab`, `checkbox`, `radio`, `switch`
+- `menuitem`, `menuitemcheckbox`, `menuitemradio`
+- `option`, `treeitem`
+- `dialog`, `alertdialog`
+
+## 예제
+
+### 올바른 패턴 ✅
+
+```jsx
+// 삼항 연산자로 문자열 변환
+<button aria-expanded={isOpen ? 'true' : 'false'}>토글</button>
+
+// String() 함수
+<button aria-pressed={String(isPressed)}>토글</button>
+
+// .toString() 메서드
+<div aria-hidden={isHidden.toString()}>내용</div>
+
+// 반전된 boolean을 삼항 연산자로
+<button aria-expanded={!isOpen ? 'true' : 'false'}>토글</button>
+
+// 비인터랙티브 요소의 정적 ARIA (핸들러 없음)
+<div aria-label="정적 레이블">내용</div>
+```
+
+### 잘못된 패턴 ❌
+
+```jsx
+// Boolean 직접 바인딩
+<button aria-expanded={isOpen}>토글</button>
+// 수정: aria-expanded={isOpen ? 'true' : 'false'}
+
+// 문자열 변환 없는 논리 표현식
+<button aria-expanded={foo && bar}>토글</button>
+// 수정: aria-expanded={foo && bar ? 'true' : 'false'}
+
+// 이벤트 핸들러와 정적 값
+<button onClick={handleClick} aria-expanded="false">토글</button>
+// 수정: 동적 상태 바인딩 사용
+
+// 인터랙티브 role과 정적 ARIA
+<div role="tab" aria-selected="true">탭</div>
+// 수정: 동적 상태 바인딩 사용
+```
+
+## 기술 구현
+
+### 기술 스택
+
+- **기반:** ESLint 플러그인 (Node.js 환경)
+- **파서:** JSX/TSX AST 파싱을 위한 `@babel/eslint-parser` 또는 TypeScript 파서
+- **분석:** JSX 요소에 대한 Visitor 패턴
+
+### 분석 로직
+
+1. **JSXElement 순회:** `role` 및 `aria-*` 속성 식별
+2. **스코프 추적:** `context.getScope()`를 사용하여 ARIA 속성에 바인딩된 변수 추적
+3. **상태 추론:** 값이 `useState` 훅이나 props에서 파생되었는지 판단
+4. **패턴 검증:** 올바른 문자열 변환 패턴 확인
+
+## 기대 효과
+
+### 1. 접근성 품질 향상
+
+런타임에서만 발견되던 동적 ARIA 오류를 빌드/CI 단계에서 선제적으로 감지
+
+### 2. 개발자 생산성
+
+`eslint --fix`로 반복적인 ARIA 상태 바인딩 오류를 자동 수정
+
+### 3. 표준화
+
+프로젝트 전반에 걸쳐 일관된 동적 ARIA 사용 패턴 강제
+
+## 개발
+
+### 테스트 실행
+
+```bash
+npm test
+```
+
+### 빌드
+
+```bash
+npm run build  # 해당되는 경우
+```
+
+## 기여
+
+기여는 언제나 환영합니다! 이슈나 풀 리퀘스트를 자유롭게 제출해주세요.
+
+## 라이선스
+
+ISC
+
+## 키워드
+
+- eslint
+- eslint-plugin
+- accessibility
+- a11y
+- aria
+- jsx
+- react
+- state-validation
+- dynamic-attributes
+
+## 관련 프로젝트
+
+- [eslint-plugin-jsx-a11y](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y) - 포괄적인 JSX 접근성 검사
+- [axe-core](https://github.com/dequelabs/axe-core) - 런타임 접근성 테스팅 엔진
+
+---
+
+**참고:** 이 플러그인은 ARIA 상태 바인딩 패턴의 정적 분석에 집중합니다. 포괄적인 접근성 테스팅을 위해 axe-core 같은 런타임 테스팅 도구와 함께 사용하세요.