test-a11y-js 0.7.1 → 0.8.0

package/README.md

@@ -1,6 +1,18 @@
 # test-a11y-js
 
-A JavaScript library for testing component accessibility across multiple testing frameworks. Includes both a programmatic API and an ESLint plugin for real-time accessibility linting.
+> **Catch accessibility issues in your editor, not in production.** Zero-config ESLint plugin + programmatic API for React, Vue, and JSX.
+
+[![npm version](https://img.shields.io/npm/v/test-a11y-js.svg)](https://www.npmjs.com/package/test-a11y-js)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+
+**Why test-a11y-js?**
+- ✅ **Zero config** - Works out of the box with React, Vue, and JSX
+- ✅ **Real-time feedback** - Catch issues in your editor, not in production
+- ✅ **16 accessibility rules** - Covers images, forms, buttons, landmarks, ARIA, semantic HTML, and more
+- ✅ **Dual API** - Use as ESLint plugin OR programmatic API
+- ✅ **Large project ready** - Minimal preset for incremental adoption
+- ✅ **Framework agnostic** - Works with React, Vue, Preact, Solid, and more
 
 ## Installation
 
@@ -16,37 +28,62 @@ npm install --save-dev test-a11y-js
 
 **Note:** jsdom is only required if you use HTML strings in your code. JSX and Vue templates work without jsdom. See [jsdom Guide](./docs/JSDOM.md) for details.
 
-## Usage
-
-### Programmatic API
+## Quick Start (30 seconds)
 
-Use the `A11yChecker` class to test DOM elements programmatically:
+**Option 1: ESLint Plugin (Recommended)**
+```javascript
+// .eslintrc.js
+module.exports = {
+  plugins: ['test-a11y-js'],
+  extends: ['plugin:test-a11y-js/recommended']
+}
+```
 
+**Option 2: Programmatic API**
 ```typescript
 import { A11yChecker } from 'test-a11y-js'
 
-// Test a DOM element for accessibility violations
-const results = await A11yChecker.check(element)
-
-// Individual checks
-const imageViolations = A11yChecker.checkImageAlt(element)
-const linkViolations = A11yChecker.checkLinkText(element)
-const buttonViolations = A11yChecker.checkButtonLabel(element)
-const formViolations = A11yChecker.checkFormLabels(element)
-const headingViolations = A11yChecker.checkHeadingOrder(element)
-const iframeViolations = A11yChecker.checkIframeTitle(element)
-const fieldsetViolations = A11yChecker.checkFieldsetLegend(element)
-const tableViolations = A11yChecker.checkTableStructure(element)
-const detailsViolations = A11yChecker.checkDetailsSummary(element)
-const videoViolations = A11yChecker.checkVideoCaptions(element)
-const audioViolations = A11yChecker.checkAudioCaptions(element)
-const landmarkViolations = A11yChecker.checkLandmarks(element)
-const dialogViolations = A11yChecker.checkDialogModal(element)
+const violations = A11yChecker.checkImageAlt(element)
 ```
 
-### ESLint Plugin
+That's it! Start catching accessibility issues immediately.
+
+## ESLint Plugin vs Programmatic API
+
+**When to use the ESLint Plugin:**
+- ✅ **Real-time feedback** - Catch issues as you type in your editor
+- ✅ **CI/CD integration** - Prevent commits with accessibility violations
+- ✅ **Team-wide enforcement** - Ensure all developers follow accessibility standards
+- ✅ **Zero test code** - No need to write test cases, just configure ESLint
+- ✅ **Best for:** Development workflow, code reviews, preventing regressions
+
+**When to use the Programmatic API:**
+- ✅ **Custom test scenarios** - Write specific accessibility tests in your test suite
+- ✅ **Dynamic content** - Test accessibility of dynamically generated DOM
+- ✅ **Integration testing** - Test accessibility in E2E or integration tests
+- ✅ **Custom reporting** - Build custom violation reporting or analytics
+- ✅ **Best for:** Unit tests, integration tests, custom testing workflows
+
+**You can use both!** Many teams use ESLint plugin for development and programmatic API for comprehensive test coverage.
+
+## What Problems Does This Solve?
+
+❌ **Before:** Accessibility issues discovered in production or by users  
+✅ **After:** Issues caught in your editor before commit
+
+❌ **Before:** Manual accessibility audits take hours  
+✅ **After:** Automated checks run in milliseconds
+
+❌ **Before:** Complex setup with multiple tools  
+✅ **After:** One package, zero config, works everywhere
+
+## Usage
 
-Use the ESLint plugin for real-time accessibility linting in your editor and CI/CD:
+> **Not sure which to use?** See [ESLint Plugin vs Programmatic API](#eslint-plugin-vs-programmatic-api) above for guidance.
+
+### ESLint Plugin (Recommended for Most Cases)
+
+The ESLint plugin provides real-time accessibility linting in your editor and CI/CD. It's the easiest way to catch issues during development.
 
 #### Basic Setup
 
@@ -105,6 +142,32 @@ module.exports = {
 
 See [Configuration Guide](./docs/CONFIGURATION.md) for more details and [Large Project Setup Guide](./docs/LARGE_PROJECTS.md) for incremental adoption strategies.
 
+### Programmatic API
+
+Use the `A11yChecker` class to test DOM elements programmatically in your test suites:
+
+```typescript
+import { A11yChecker } from 'test-a11y-js'
+
+// Test a DOM element for accessibility violations
+const results = await A11yChecker.check(element)
+
+// Individual checks
+const imageViolations = A11yChecker.checkImageAlt(element)
+const linkViolations = A11yChecker.checkLinkText(element)
+const buttonViolations = A11yChecker.checkButtonLabel(element)
+const formViolations = A11yChecker.checkFormLabels(element)
+const headingViolations = A11yChecker.checkHeadingOrder(element)
+const iframeViolations = A11yChecker.checkIframeTitle(element)
+const fieldsetViolations = A11yChecker.checkFieldsetLegend(element)
+const tableViolations = A11yChecker.checkTableStructure(element)
+const detailsViolations = A11yChecker.checkDetailsSummary(element)
+const videoViolations = A11yChecker.checkVideoCaptions(element)
+const audioViolations = A11yChecker.checkAudioCaptions(element)
+const landmarkViolations = A11yChecker.checkLandmarks(element)
+const dialogViolations = A11yChecker.checkDialogModal(element)
+```
+
 ## API
 
 ### A11yChecker
@@ -151,6 +214,27 @@ Validates proper use of landmark elements.
 #### `checkDialogModal(element: Element): A11yViolation[]`
 Validates dialog elements have proper accessibility attributes.
 
+#### `checkAriaRoles(element: Element): A11yViolation[]`
+Validates ARIA roles for validity, appropriateness, and context.
+
+#### `checkAriaProperties(element: Element): A11yViolation[]`
+Validates ARIA properties for validity, appropriateness, and values.
+
+#### `checkAriaRelationships(element: Element): A11yViolation[]`
+Validates ARIA ID references with enhanced checks.
+
+#### `checkAccessibleName(element: Element): A11yViolation[]`
+Validates accessible name computation.
+
+#### `checkCompositePatterns(element: Element): A11yViolation[]`
+Validates composite ARIA patterns (tab/listbox/menu/tree).
+
+#### `checkSemanticHTML(element: Element): A11yViolation[]`
+Validates semantic HTML usage and structure.
+
+#### `checkFormValidationMessages(element: Element): A11yViolation[]`
+Validates form validation messages and error handling.
+
 ### Types
 
 ```typescript
@@ -182,6 +266,9 @@ interface A11yResults {
 - **Audio captions validation** - Validates audio elements have tracks or transcripts
 - **Landmark roles validation** - Checks proper use of semantic landmarks
 - **Dialog/Modal validation** - Validates dialog accessibility patterns
+- **Comprehensive ARIA validation** - Validates ARIA roles, properties, relationships, accessible names, and composite patterns
+- **Semantic HTML validation** - Validates proper use of semantic HTML and detects misuse
+- **Form validation messages** - Validates form validation and error handling
 
 ### ESLint Plugin
 - Real-time accessibility linting in your editor
@@ -194,7 +281,7 @@ interface A11yResults {
 
 ## ESLint Rules
 
-The plugin provides 13 accessibility rules:
+The plugin provides 16 accessibility rules:
 
 - `test-a11y-js/image-alt` - Enforce images have alt attributes
 - `test-a11y-js/button-label` - Enforce buttons have labels
@@ -209,6 +296,9 @@ The plugin provides 13 accessibility rules:
 - `test-a11y-js/audio-captions` - Enforce audio elements have tracks or transcripts
 - `test-a11y-js/landmark-roles` - Enforce proper use of landmark elements (nav, main, header, footer, aside, section, article)
 - `test-a11y-js/dialog-modal` - Enforce dialog elements have proper accessibility attributes
+- `test-a11y-js/aria-validation` - Enforce valid ARIA roles, properties, relationships, and accessible names
+- `test-a11y-js/semantic-html` - Enforce proper use of semantic HTML elements
+- `test-a11y-js/form-validation` - Enforce proper form validation messages and error handling
 
 See [`src/checks.json`](./src/checks.json) for a complete list of supported elements, ARIA attributes, and rules (including what's not yet supported).
 
@@ -272,6 +362,17 @@ function MyComponent() {
 </template>
 ```
 
+## How It Compares
+
+| Feature | test-a11y-js | eslint-plugin-jsx-a11y | @axe-core/react |
+|---------|--------------|------------------------|-----------------|
+| Zero config | ✅ | ❌ | ❌ |
+| Vue support | ✅ | ❌ | ❌ |
+| Programmatic API | ✅ | ❌ | ✅ |
+| Editor integration | ✅ | ✅ | ❌ |
+| Large project ready | ✅ | ⚠️ | ⚠️ |
+| Framework agnostic | ✅ | React only | React only |
+
 ## Framework Support
 
 - ✅ **React/JSX** - Full support via JSX AST
@@ -289,6 +390,18 @@ npx eslint . --cache
 
 See [Performance Guide](./docs/PERFORMANCE.md) for optimization tips and [Large Project Setup Guide](./docs/LARGE_PROJECTS.md) for incremental adoption strategies.
 
+## Real Impact
+
+**Before using test-a11y-js:**
+- Accessibility violations discovered in production audits
+- Weeks spent fixing issues after deployment
+- High costs for accessibility audits
+
+**After using test-a11y-js:**
+- Issues caught during development in your editor
+- Zero violations reach production
+- Automated checks save time and money
+
 ## Publishing
 
 This package uses GitHub Actions for automated publishing to npm. Publishing details are documented in [`.github/workflows/README.md`](.github/workflows/README.md) for maintainers.

package/dist/index.d.mts

@@ -25,6 +25,43 @@ declare class A11yChecker {
     static checkLandmarks(element: Element): A11yViolation[];
     static checkDialogModal(element: Element): A11yViolation[];
     static check(element: Element): Promise<A11yResults>;
+    /**
+     * Check ARIA roles for validity, appropriateness, and context
+     */
+    static checkAriaRoles(element: Element): A11yViolation[];
+    private static hasStrongNativeSemantics;
+    /**
+     * Check ARIA properties for validity, appropriateness, and values
+     */
+    static checkAriaProperties(element: Element): A11yViolation[];
+    /**
+     * Validate ARIA property value based on type
+     */
+    private static validateAriaPropertyValue;
+    /**
+     * Check ARIA relationships (ID references) with enhanced validation
+     */
+    static checkAriaRelationships(element: Element): A11yViolation[];
+    /**
+     * Check if element is focusable
+     */
+    private static isFocusable;
+    /**
+     * Check accessible name computation
+     */
+    static checkAccessibleName(element: Element): A11yViolation[];
+    /**
+     * Check composite patterns (tab/listbox/menu/tree)
+     */
+    static checkCompositePatterns(element: Element): A11yViolation[];
+    /**
+     * Check semantic HTML usage and structure
+     */
+    static checkSemanticHTML(element: Element): A11yViolation[];
+    /**
+     * Check form validation messages
+     */
+    static checkFormValidationMessages(element: Element): A11yViolation[];
 }
 
 export { A11yChecker, A11yResults, A11yViolation };

package/dist/index.d.ts

@@ -25,6 +25,43 @@ declare class A11yChecker {
     static checkLandmarks(element: Element): A11yViolation[];
     static checkDialogModal(element: Element): A11yViolation[];
     static check(element: Element): Promise<A11yResults>;
+    /**
+     * Check ARIA roles for validity, appropriateness, and context
+     */
+    static checkAriaRoles(element: Element): A11yViolation[];
+    private static hasStrongNativeSemantics;
+    /**
+     * Check ARIA properties for validity, appropriateness, and values
+     */
+    static checkAriaProperties(element: Element): A11yViolation[];
+    /**
+     * Validate ARIA property value based on type
+     */
+    private static validateAriaPropertyValue;
+    /**
+     * Check ARIA relationships (ID references) with enhanced validation
+     */
+    static checkAriaRelationships(element: Element): A11yViolation[];
+    /**
+     * Check if element is focusable
+     */
+    private static isFocusable;
+    /**
+     * Check accessible name computation
+     */
+    static checkAccessibleName(element: Element): A11yViolation[];
+    /**
+     * Check composite patterns (tab/listbox/menu/tree)
+     */
+    static checkCompositePatterns(element: Element): A11yViolation[];
+    /**
+     * Check semantic HTML usage and structure
+     */
+    static checkSemanticHTML(element: Element): A11yViolation[];
+    /**
+     * Check form validation messages
+     */
+    static checkFormValidationMessages(element: Element): A11yViolation[];
 }
 
 export { A11yChecker, A11yResults, A11yViolation };