eslint-plugin-aria-state-validator 1.0.0

package/README.md

@@ -0,0 +1,360 @@
+# eslint-plugin-aria-state-validator
+
+Comprehensive ESLint plugin for ARIA accessibility validation:
+- **Dynamic State Validation**: Validates that ARIA state attributes are properly bound to component state
+- **Static ARIA Validation**: Validates static ARIA attributes for correctness (spelling, values, conflicts)
+
+Catches both runtime and static accessibility errors at build time.
+
+## Problem Statement: The "Runtime Gap" in Static Analysis
+
+Existing accessibility tools like `eslint-plugin-jsx-a11y` validate the syntactic correctness of ARIA attributes (e.g., ensuring `aria-expanded` uses `'true'` or `'false'`), but they **cannot verify** whether these attributes are correctly connected to the component's JavaScript state and dynamically updated at runtime.
+
+### Issues This Causes:
+
+- Toggle buttons with `aria-expanded="false"` hardcoded, never changing when opened
+- Boolean values directly bound to ARIA attributes: `aria-expanded={isOpen}` (incorrect - should be string)
+- Static ARIA states on interactive elements that should be dynamic
+- Screen readers receiving inaccurate information about component states
+
+## Core Concept: State-Dependent ARIA Validation
+
+This plugin uses AST (Abstract Syntax Tree) analysis to **statically verify** that ARIA state attributes are logically connected to component state (State/Props) and will update dynamically at runtime.
+
+### Key Differentiator
+
+Goes beyond syntax checking to infer component **dynamic behavior**, proactively catching runtime accessibility errors during build/CI phase.
+
+## Installation
+
+```bash
+npm install --save-dev eslint-plugin-aria-state-validator
+```
+
+## Usage
+
+### 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'
+    }
+  }
+];
+```
+
+### Legacy ESLintRC Config
+
+```json
+{
+  "plugins": ["aria-state-validator"],
+  "rules": {
+    "aria-state-validator/state-dependent-aria-validator": "warn"
+  }
+}
+```
+
+## Two Rules for Comprehensive ARIA Validation
+
+This plugin provides two complementary rules:
+
+### Rule 1: `state-dependent-aria-validator` (Dynamic State Validation)
+
+Validates that ARIA **state** attributes are properly bound to component state and update dynamically.
+
+### Rule 2: `static-aria-validator` (Static ARIA Validation)
+
+Validates the **correctness** of ARIA attributes when they are used:
+- Valid ARIA property names (catches typos)
+- Correct values for boolean and enum ARIA attributes
+- No conflicting ARIA attributes
+- No redundant roles on native HTML elements
+
+**Note:** This plugin validates **how** ARIA attributes are used, not **whether** they should be used. For enforcing the presence of accessibility features, use [eslint-plugin-jsx-a11y](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y).
+
+## Features & Validation Patterns
+
+### 1. Boolean Value Direct Binding Detection
+
+**Detects:** Direct binding of Boolean values to ARIA attributes
+
+```jsx
+// ❌ Error: Boolean value directly bound
+<button aria-expanded={isOpen}>Toggle</button>
+
+// ✅ Correct: Explicit string conversion
+<button aria-expanded={isOpen ? 'true' : 'false'}>Toggle</button>
+```
+
+**Auto-fix Available:** `eslint --fix` will automatically convert to proper string format
+
+### 2. Static Value + Interactive Handler Detection
+
+**Detects:** Static ARIA state values on elements with event handlers
+
+```jsx
+// ❌ Error: Has onClick but aria-expanded is static
+<button onClick={handleClick} aria-expanded="false">
+  Toggle
+</button>
+
+// ✅ Correct: Dynamic state binding
+<button onClick={handleClick} aria-expanded={isOpen ? 'true' : 'false'}>
+  Toggle
+</button>
+```
+
+**Smart Auto-fix:** When the handler contains state variable references (e.g., `() => setExpanded(!expanded)`), the plugin automatically extracts the variable name and binds it to the ARIA attribute:
+
+```jsx
+// ❌ Before auto-fix
+<div onClick={() => setExpanded(!expanded)} aria-expanded="false">
+  Click to expand
+</div>
+
+// ✅ After auto-fix (automatically detects 'expanded' variable)
+<div onClick={() => setExpanded(!expanded)} aria-expanded={expanded ? 'true' : 'false'}>
+  Click to expand
+</div>
+```
+
+### 3. Role-Based State Association Validation
+
+**Detects:** Interactive roles with static ARIA states
+
+```jsx
+// ❌ Error: role="button" with static aria-pressed
+<div role="button" aria-pressed="false">Button</div>
+
+// ✅ Correct: Dynamic state binding
+<div role="button" aria-pressed={isPressed ? 'true' : 'false'}>Button</div>
+```
+
+---
+
+## Static ARIA Validation Patterns
+
+### 4. Invalid ARIA Property Detection
+
+**Detects:** Typos in ARIA attribute names
+
+```jsx
+// ❌ Error: Typo in aria-label
+<button aria-labell="Close">X</button>
+
+// ✅ Correct: Proper spelling
+<button aria-label="Close">X</button>
+```
+
+### 5. Empty Required Values
+
+**Detects:** ARIA attributes that require non-empty values
+
+```jsx
+// ❌ Error: Empty aria-label
+<div aria-label="">Content</div>
+
+// ✅ Correct: Non-empty value
+<div aria-label="Description">Content</div>
+```
+
+### 6. Invalid Boolean Values
+
+**Detects:** Incorrect boolean-like values
+
+```jsx
+// ❌ Error: Invalid boolean value
+<div aria-hidden="yes">Content</div>
+<div aria-disabled="1">Content</div>
+
+// ✅ Correct: Use "true" or "false"
+<div aria-hidden="true">Content</div>
+<div aria-disabled="false">Content</div>
+```
+
+### 7. Invalid Enum Values
+
+**Detects:** Invalid values for enum-type ARIA attributes
+
+```jsx
+// ❌ Error: Invalid aria-live value
+<div aria-live="loud">Live region</div>
+
+// ✅ Correct: Use valid enum value
+<div aria-live="polite">Live region</div>
+
+// Valid values: "off", "polite", "assertive"
+```
+
+### 8. Conflicting ARIA Attributes
+
+**Detects:** aria-label and aria-labelledby used together
+
+```jsx
+// ❌ Error: Both attributes present (aria-labelledby takes precedence)
+<div aria-label="Label" aria-labelledby="other-id">Content</div>
+
+// ✅ Correct: Use only one
+<div aria-labelledby="other-id">Content</div>
+```
+
+### 9. Redundant Roles
+
+**Detects:** Explicit roles that match native HTML semantics
+
+```jsx
+// ❌ Error: Redundant role
+<button role="button">Click me</button>
+<nav role="navigation">Nav</nav>
+<a href="#" role="link">Link</a>
+
+// ✅ Correct: Use native semantics
+<button>Click me</button>
+<nav>Nav</nav>
+<a href="#">Link</a>
+```
+
+---
+
+## Supported ARIA Attributes (Dynamic Validation)
+
+The plugin validates these dynamic ARIA state attributes:
+
+- `aria-expanded` - Toggle buttons, expandable elements
+- `aria-selected` - Tabs, selectable options
+- `aria-checked` - Checkboxes, radio buttons
+- `aria-pressed` - Toggle buttons
+- `aria-hidden` - Dynamically shown/hidden elements
+- `aria-disabled` - Dynamically enabled/disabled elements
+- `aria-modal` - Dialogs, modals
+- `aria-current` - Current active item indicators
+
+## Supported Interactive Roles
+
+Elements with these roles are expected to have dynamic ARIA states:
+
+- `button`, `tab`, `checkbox`, `radio`, `switch`
+- `menuitem`, `menuitemcheckbox`, `menuitemradio`
+- `option`, `treeitem`
+- `dialog`, `alertdialog`
+
+## Examples
+
+### Valid Patterns ✅
+
+```jsx
+// Ternary operator for string conversion
+<button aria-expanded={isOpen ? 'true' : 'false'}>Toggle</button>
+
+// String() function
+<button aria-pressed={String(isPressed)}>Toggle</button>
+
+// .toString() method
+<div aria-hidden={isHidden.toString()}>Content</div>
+
+// Inverted boolean with ternary
+<button aria-expanded={!isOpen ? 'true' : 'false'}>Toggle</button>
+
+// Static ARIA on non-interactive element (no handler)
+<div aria-label="static label">Content</div>
+```
+
+### Invalid Patterns ❌
+
+```jsx
+// Direct boolean binding
+<button aria-expanded={isOpen}>Toggle</button>
+// Fix: aria-expanded={isOpen ? 'true' : 'false'}
+
+// Logical expression without string conversion
+<button aria-expanded={foo && bar}>Toggle</button>
+// Fix: aria-expanded={foo && bar ? 'true' : 'false'}
+
+// Static value with event handler
+<button onClick={handleClick} aria-expanded="false">Toggle</button>
+// Fix: Use dynamic state binding
+
+// Interactive role with static ARIA
+<div role="tab" aria-selected="true">Tab</div>
+// Fix: Use dynamic state binding
+```
+
+## Technical Implementation
+
+### Technology Stack
+
+- **Base:** ESLint plugin (Node.js environment)
+- **Parser:** `@babel/eslint-parser` or TypeScript parser for JSX/TSX AST parsing
+- **Analysis:** Visitor pattern on JSX elements
+
+### Analysis Logic
+
+1. **JSXElement Traversal:** Identifies `role` and `aria-*` attributes
+2. **Scope Tracking:** Uses `context.getScope()` to trace variables bound to ARIA attributes
+3. **State Inference:** Determines if values derive from `useState` hooks or props
+4. **Pattern Validation:** Checks for proper string conversion patterns
+
+## Expected Benefits
+
+### 1. Accessibility Quality Improvement
+
+Catch dynamic ARIA errors at build/CI phase instead of runtime
+
+### 2. Developer Productivity
+
+Auto-fix repetitive ARIA state binding errors with `eslint --fix`
+
+### 3. Standardization
+
+Enforce consistent dynamic ARIA usage patterns across projects
+
+## Development
+
+### Running Tests
+
+```bash
+npm test
+```
+
+### Building
+
+```bash
+npm run build  # If applicable
+```
+
+## Contributing
+
+Contributions welcome! Please feel free to submit issues or pull requests.
+
+## License
+
+ISC
+
+## Keywords
+
+- eslint
+- eslint-plugin
+- accessibility
+- a11y
+- aria
+- jsx
+- react
+- state-validation
+- dynamic-attributes
+
+## Related Projects
+
+- [eslint-plugin-jsx-a11y](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y) - Comprehensive JSX accessibility checking
+- [axe-core](https://github.com/dequelabs/axe-core) - Runtime accessibility testing engine
+
+---
+
+**Note:** This plugin focuses on static analysis of ARIA state binding patterns. For comprehensive accessibility testing, combine with runtime testing tools like axe-core.

package/index.js

@@ -0,0 +1,37 @@
+const stateDependentAriaValidator = require('./lib/rules/state-dependent-aria-validator');
+const staticAriaValidator = require('./lib/rules/static-aria-validator');
+
+module.exports = {
+  rules: {
+    'state-dependent-aria-validator': stateDependentAriaValidator,
+    'static-aria-validator': staticAriaValidator
+  },
+  configs: {
+    recommended: {
+      plugins: ['aria-state-validator'],
+      rules: {
+        'aria-state-validator/state-dependent-aria-validator': 'warn',
+        'aria-state-validator/static-aria-validator': 'warn'
+      }
+    },
+    strict: {
+      plugins: ['aria-state-validator'],
+      rules: {
+        'aria-state-validator/state-dependent-aria-validator': 'error',
+        'aria-state-validator/static-aria-validator': 'error'
+      }
+    },
+    'dynamic-only': {
+      plugins: ['aria-state-validator'],
+      rules: {
+        'aria-state-validator/state-dependent-aria-validator': 'warn'
+      }
+    },
+    'static-only': {
+      plugins: ['aria-state-validator'],
+      rules: {
+        'aria-state-validator/static-aria-validator': 'warn'
+      }
+    }
+  }
+};