eslint-plugin-react-a11y 2.1.0

package/src/index.js

@@ -0,0 +1,279 @@
+"use strict";
+/**
+ * Copyright (c) 2025 Ofri Peretz
+ * Licensed under the MIT License. Use of this source code is governed by the
+ * MIT license that can be found in the LICENSE file.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configs = exports.plugin = exports.rules = void 0;
+const tslib_1 = require("tslib");
+// Anchor rules
+const anchor_ambiguous_text_1 = require("./rules/anchor-ambiguous-text");
+const anchor_has_content_1 = require("./rules/anchor-has-content");
+const anchor_is_valid_1 = require("./rules/anchor-is-valid");
+// ARIA rules
+const aria_activedescendant_has_tabindex_1 = require("./rules/aria-activedescendant-has-tabindex");
+const aria_props_1 = require("./rules/aria-props");
+const aria_role_1 = require("./rules/aria-role");
+const aria_unsupported_elements_1 = require("./rules/aria-unsupported-elements");
+// Form & Input rules
+const autocomplete_valid_1 = require("./rules/autocomplete-valid");
+const control_has_associated_label_1 = require("./rules/control-has-associated-label");
+const label_has_associated_control_1 = require("./rules/label-has-associated-control");
+// Event rules
+const click_events_have_key_events_1 = require("./rules/click-events-have-key-events");
+const mouse_events_have_key_events_1 = require("./rules/mouse-events-have-key-events");
+// Content rules
+const heading_has_content_1 = require("./rules/heading-has-content");
+const html_has_lang_1 = require("./rules/html-has-lang");
+const iframe_has_title_1 = require("./rules/iframe-has-title");
+const lang_1 = require("./rules/lang");
+const media_has_caption_1 = require("./rules/media-has-caption");
+// Image rules
+const img_redundant_alt_1 = require("./rules/img-redundant-alt");
+const alt_text_1 = require("./rules/alt-text");
+// Interactive element rules
+const interactive_supports_focus_1 = require("./rules/interactive-supports-focus");
+const no_interactive_element_to_noninteractive_role_1 = require("./rules/no-interactive-element-to-noninteractive-role");
+const no_noninteractive_element_interactions_1 = require("./rules/no-noninteractive-element-interactions");
+const no_noninteractive_element_to_interactive_role_1 = require("./rules/no-noninteractive-element-to-interactive-role");
+const no_noninteractive_tabindex_1 = require("./rules/no-noninteractive-tabindex");
+const no_static_element_interactions_1 = require("./rules/no-static-element-interactions");
+// Focus & Navigation rules
+const no_access_key_1 = require("./rules/no-access-key");
+const no_aria_hidden_on_focusable_1 = require("./rules/no-aria-hidden-on-focusable");
+const no_autofocus_1 = require("./rules/no-autofocus");
+const no_keyboard_inaccessible_elements_1 = require("./rules/no-keyboard-inaccessible-elements");
+const tabindex_no_positive_1 = require("./rules/tabindex-no-positive");
+// Visual & Distraction rules
+const no_distracting_elements_1 = require("./rules/no-distracting-elements");
+const no_missing_aria_labels_1 = require("./rules/no-missing-aria-labels");
+const no_redundant_roles_1 = require("./rules/no-redundant-roles");
+// Role rules
+const role_has_required_aria_props_1 = require("./rules/role-has-required-aria-props");
+const role_supports_aria_props_1 = require("./rules/role-supports-aria-props");
+const prefer_tag_over_role_1 = require("./rules/prefer-tag-over-role");
+// Scope rule
+const scope_1 = require("./rules/scope");
+/**
+ * Collection of all accessibility ESLint rules
+ */
+exports.rules = {
+    // Anchor rules
+    'anchor-ambiguous-text': anchor_ambiguous_text_1.anchorAmbiguousText,
+    'anchor-has-content': anchor_has_content_1.anchorHasContent,
+    'anchor-is-valid': anchor_is_valid_1.anchorIsValid,
+    // ARIA rules
+    'aria-activedescendant-has-tabindex': aria_activedescendant_has_tabindex_1.ariaActivedescendantHasTabindex,
+    'aria-props': aria_props_1.ariaProps,
+    'aria-role': aria_role_1.ariaRole,
+    'aria-unsupported-elements': aria_unsupported_elements_1.ariaUnsupportedElements,
+    // Form & Input rules
+    'autocomplete-valid': autocomplete_valid_1.autocompleteValid,
+    'control-has-associated-label': control_has_associated_label_1.controlHasAssociatedLabel,
+    'label-has-associated-control': label_has_associated_control_1.labelHasAssociatedControl,
+    // Event rules
+    'click-events-have-key-events': click_events_have_key_events_1.clickEventsHaveKeyEvents,
+    'mouse-events-have-key-events': mouse_events_have_key_events_1.mouseEventsHaveKeyEvents,
+    // Content rules
+    'heading-has-content': heading_has_content_1.headingHasContent,
+    'html-has-lang': html_has_lang_1.htmlHasLang,
+    'iframe-has-title': iframe_has_title_1.iframeHasTitle,
+    'lang': lang_1.lang,
+    'media-has-caption': media_has_caption_1.mediaHasCaption,
+    // Image rules
+    'img-redundant-alt': img_redundant_alt_1.imgRedundantAlt,
+    'alt-text': alt_text_1.altText,
+    // Interactive element rules
+    'interactive-supports-focus': interactive_supports_focus_1.interactiveSupportsFocus,
+    'no-interactive-element-to-noninteractive-role': no_interactive_element_to_noninteractive_role_1.noInteractiveElementToNoninteractiveRole,
+    'no-noninteractive-element-interactions': no_noninteractive_element_interactions_1.noNoninteractiveElementInteractions,
+    'no-noninteractive-element-to-interactive-role': no_noninteractive_element_to_interactive_role_1.noNoninteractiveElementToInteractiveRole,
+    'no-noninteractive-tabindex': no_noninteractive_tabindex_1.noNoninteractiveTabindex,
+    'no-static-element-interactions': no_static_element_interactions_1.noStaticElementInteractions,
+    // Focus & Navigation rules
+    'no-access-key': no_access_key_1.noAccessKey,
+    'no-aria-hidden-on-focusable': no_aria_hidden_on_focusable_1.noAriaHiddenOnFocusable,
+    'no-autofocus': no_autofocus_1.noAutofocus,
+    'no-keyboard-inaccessible-elements': no_keyboard_inaccessible_elements_1.noKeyboardInaccessibleElements,
+    'tabindex-no-positive': tabindex_no_positive_1.tabindexNoPositive,
+    // Visual & Distraction rules
+    'no-distracting-elements': no_distracting_elements_1.noDistractingElements,
+    'no-missing-aria-labels': no_missing_aria_labels_1.noMissingAriaLabels,
+    'no-redundant-roles': no_redundant_roles_1.noRedundantRoles,
+    // Role rules
+    'role-has-required-aria-props': role_has_required_aria_props_1.roleHasRequiredAriaProps,
+    'role-supports-aria-props': role_supports_aria_props_1.roleSupportsAriaProps,
+    'prefer-tag-over-role': prefer_tag_over_role_1.preferTagOverRole,
+    // Scope rule
+    'scope': scope_1.scope,
+};
+/**
+ * ESLint Plugin object
+ */
+exports.plugin = {
+    meta: {
+        name: 'eslint-plugin-react-a11y',
+        version: '1.0.0',
+    },
+    rules: exports.rules,
+};
+/**
+ * Preset configurations for accessibility rules
+ */
+exports.configs = {
+    /**
+     * Recommended accessibility configuration
+     *
+     * Enables critical accessibility rules with sensible severity levels:
+     * - WCAG Level A violations as errors
+     * - WCAG Level AA/AAA as warnings
+     */
+    recommended: {
+        plugins: {
+            'react-a11y': exports.plugin,
+        },
+        rules: {
+            // WCAG 2.1 Level A - Critical (errors)
+            'react-a11y/alt-text': 'error',
+            'react-a11y/anchor-has-content': 'error',
+            'react-a11y/aria-props': 'error',
+            'react-a11y/aria-role': 'error',
+            'react-a11y/aria-unsupported-elements': 'error',
+            'react-a11y/role-has-required-aria-props': 'error',
+            'react-a11y/role-supports-aria-props': 'error',
+            'react-a11y/html-has-lang': 'error',
+            'react-a11y/lang': 'error',
+            'react-a11y/heading-has-content': 'error',
+            'react-a11y/iframe-has-title': 'error',
+            'react-a11y/no-distracting-elements': 'error',
+            'react-a11y/scope': 'error',
+            'react-a11y/no-aria-hidden-on-focusable': 'error',
+            // WCAG 2.1 Level A - Keyboard accessibility
+            'react-a11y/click-events-have-key-events': 'error',
+            'react-a11y/no-keyboard-inaccessible-elements': 'error',
+            'react-a11y/interactive-supports-focus': 'error',
+            'react-a11y/no-noninteractive-element-interactions': 'warn',
+            'react-a11y/no-static-element-interactions': 'warn',
+            // WCAG 2.1 Level AA - Important (warnings)
+            'react-a11y/anchor-is-valid': 'warn',
+            'react-a11y/anchor-ambiguous-text': 'warn',
+            'react-a11y/autocomplete-valid': 'warn',
+            'react-a11y/control-has-associated-label': 'warn',
+            'react-a11y/label-has-associated-control': 'warn',
+            'react-a11y/media-has-caption': 'warn',
+            'react-a11y/mouse-events-have-key-events': 'warn',
+            'react-a11y/no-access-key': 'warn',
+            'react-a11y/no-autofocus': 'warn',
+            'react-a11y/no-redundant-roles': 'warn',
+            'react-a11y/tabindex-no-positive': 'warn',
+            'react-a11y/aria-activedescendant-has-tabindex': 'warn',
+            // Best practices (warnings)
+            'react-a11y/img-redundant-alt': 'warn',
+            'react-a11y/no-missing-aria-labels': 'warn',
+            'react-a11y/prefer-tag-over-role': 'warn',
+            'react-a11y/no-interactive-element-to-noninteractive-role': 'warn',
+            'react-a11y/no-noninteractive-element-to-interactive-role': 'warn',
+            'react-a11y/no-noninteractive-tabindex': 'warn',
+        },
+    },
+    /**
+     * Strict accessibility configuration
+     *
+     * All accessibility rules set to 'error' for maximum WCAG compliance
+     */
+    strict: {
+        plugins: {
+            'react-a11y': exports.plugin,
+        },
+        rules: Object.fromEntries(Object.keys(exports.rules).map(ruleName => [`react-a11y/${ruleName}`, 'error'])),
+    },
+    /**
+     * WCAG 2.1 Level A configuration
+     *
+     * Only rules required for WCAG 2.1 Level A compliance
+     */
+    'wcag-a': {
+        plugins: {
+            'react-a11y': exports.plugin,
+        },
+        rules: {
+            // 1.1.1 Non-text Content
+            'react-a11y/alt-text': 'error',
+            // 1.3.1 Info and Relationships
+            'react-a11y/heading-has-content': 'error',
+            'react-a11y/scope': 'error',
+            'react-a11y/role-has-required-aria-props': 'error',
+            // 2.1.1 Keyboard
+            'react-a11y/click-events-have-key-events': 'error',
+            'react-a11y/no-keyboard-inaccessible-elements': 'error',
+            'react-a11y/interactive-supports-focus': 'error',
+            // 2.4.4 Link Purpose
+            'react-a11y/anchor-has-content': 'error',
+            // 3.1.1 Language of Page
+            'react-a11y/html-has-lang': 'error',
+            'react-a11y/lang': 'error',
+            // 4.1.1 Parsing
+            'react-a11y/aria-props': 'error',
+            'react-a11y/aria-role': 'error',
+            'react-a11y/aria-unsupported-elements': 'error',
+            // 4.1.2 Name, Role, Value
+            'react-a11y/role-supports-aria-props': 'error',
+            'react-a11y/iframe-has-title': 'error',
+            // 2.3.1 Three Flashes or Below Threshold
+            'react-a11y/no-distracting-elements': 'error',
+        },
+    },
+    /**
+     * WCAG 2.1 Level AA configuration
+     *
+     * Includes Level A + additional rules for Level AA compliance
+     */
+    'wcag-aa': {
+        plugins: {
+            'react-a11y': exports.plugin,
+        },
+        rules: {
+            // All Level A rules
+            'react-a11y/alt-text': 'error',
+            'react-a11y/heading-has-content': 'error',
+            'react-a11y/scope': 'error',
+            'react-a11y/role-has-required-aria-props': 'error',
+            'react-a11y/click-events-have-key-events': 'error',
+            'react-a11y/no-keyboard-inaccessible-elements': 'error',
+            'react-a11y/interactive-supports-focus': 'error',
+            'react-a11y/anchor-has-content': 'error',
+            'react-a11y/html-has-lang': 'error',
+            'react-a11y/lang': 'error',
+            'react-a11y/aria-props': 'error',
+            'react-a11y/aria-role': 'error',
+            'react-a11y/aria-unsupported-elements': 'error',
+            'react-a11y/role-supports-aria-props': 'error',
+            'react-a11y/iframe-has-title': 'error',
+            'react-a11y/no-distracting-elements': 'error',
+            // Level AA additions
+            // 1.2.4 Captions (Live) & 1.2.5 Audio Description
+            'react-a11y/media-has-caption': 'error',
+            // 1.3.5 Identify Input Purpose
+            'react-a11y/autocomplete-valid': 'error',
+            // 1.4.4 Resize text (no autofocus related)
+            'react-a11y/no-autofocus': 'error',
+            // 2.4.6 Headings and Labels
+            'react-a11y/control-has-associated-label': 'error',
+            'react-a11y/label-has-associated-control': 'error',
+            // 2.4.7 Focus Visible
+            'react-a11y/tabindex-no-positive': 'error',
+            'react-a11y/no-aria-hidden-on-focusable': 'error',
+            // 3.2.1 On Focus
+            'react-a11y/mouse-events-have-key-events': 'error',
+        },
+    },
+};
+/**
+ * Default export for ESLint plugin
+ */
+exports.default = exports.plugin;
+/**
+ * Re-export types (will be created in types/index.ts)
+ */
+tslib_1.__exportStar(require("./types/index"), exports);

package/src/rules/alt-text.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Copyright (c) 2025 Ofri Peretz
+ * Licensed under the MIT License. Use of this source code is governed by the
+ * MIT license that can be found in the LICENSE file.
+ */
+/**
+ * ESLint Rule: alt-text
+ * Enforce alt text on images with user impact context
+ * Matches jsx-a11y naming convention
+ */
+import type { TSESLint } from '@interlace/eslint-devkit';
+type MessageIds = 'missingAlt' | 'emptyAlt' | 'addDescriptiveAlt' | 'useEmptyAlt';
+export interface Options {
+    /** Allow aria-label as alternative to alt text. Default: false */
+    allowAriaLabel?: boolean;
+    /** Allow aria-labelledby as alternative to alt text. Default: false */
+    allowAriaLabelledby?: boolean;
+}
+type RuleOptions = [Options?];
+export declare const altText: TSESLint.RuleModule<MessageIds, RuleOptions, unknown, TSESLint.RuleListener> & {
+    name: string;
+};
+export {};

package/src/rules/alt-text.js

@@ -0,0 +1,205 @@
+"use strict";
+/**
+ * Copyright (c) 2025 Ofri Peretz
+ * Licensed under the MIT License. Use of this source code is governed by the
+ * MIT license that can be found in the LICENSE file.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.altText = void 0;
+const eslint_devkit_1 = require("@interlace/eslint-devkit");
+const eslint_devkit_2 = require("@interlace/eslint-devkit");
+exports.altText = (0, eslint_devkit_2.createRule)({
+    name: 'alt-text',
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Enforce alt text on images with accessibility impact context',
+        },
+        fixable: 'code',
+        hasSuggestions: true,
+        messages: {
+            // 🎯 Token optimization: 45% reduction (51→28 tokens) - image alt text improves accessibility
+            missingAlt: (0, eslint_devkit_1.formatLLMMessage)({
+                icon: eslint_devkit_1.MessageIcons.ACCESSIBILITY,
+                issueName: 'Image missing alt text',
+                cwe: 'CWE-252',
+                description: 'Image missing alt text',
+                severity: 'CRITICAL',
+                fix: 'Add alt="Descriptive text about image"',
+                documentationLink: 'https://www.w3.org/WAI/tutorials/images/',
+            }),
+            emptyAlt: (0, eslint_devkit_1.formatLLMMessage)({
+                icon: eslint_devkit_1.MessageIcons.ACCESSIBILITY,
+                issueName: 'Empty Alt Text',
+                description: 'Empty alt text detected',
+                severity: 'LOW',
+                fix: 'Consider: {{consideration}}',
+                documentationLink: 'https://www.w3.org/WAI/tutorials/images/decorative/',
+            }),
+            addDescriptiveAlt: (0, eslint_devkit_1.formatLLMMessage)({
+                icon: eslint_devkit_1.MessageIcons.INFO,
+                issueName: 'Add Descriptive Alt',
+                description: 'Add descriptive alt text',
+                severity: 'LOW',
+                fix: 'alt="Descriptive text about image content"',
+                documentationLink: 'https://www.w3.org/WAI/tutorials/images/informative/',
+            }),
+            useEmptyAlt: (0, eslint_devkit_1.formatLLMMessage)({
+                icon: eslint_devkit_1.MessageIcons.INFO,
+                issueName: 'Use Empty Alt',
+                description: 'Use empty alt for decorative images',
+                severity: 'LOW',
+                fix: 'alt="" (for decorative images only)',
+                documentationLink: 'https://www.w3.org/WAI/tutorials/images/decorative/',
+            }),
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    allowAriaLabel: {
+                        type: 'boolean',
+                        default: false,
+                    },
+                    allowAriaLabelledby: {
+                        type: 'boolean',
+                        default: false,
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+    },
+    defaultOptions: [
+        {
+            allowAriaLabel: false,
+            allowAriaLabelledby: false,
+        },
+    ],
+    create(context) {
+        const options = context.options[0] || {};
+        const { allowAriaLabel = false, allowAriaLabelledby = false } = options || {};
+        /**
+         * Check if element has alt attribute
+         */
+        const hasAltAttribute = (node) => {
+            return node.attributes.some((attr) => attr.type === 'JSXAttribute' && attr.name.type === 'JSXIdentifier' && attr.name.name === 'alt');
+        };
+        /**
+         * Get alt attribute value
+         */
+        const getAltValue = (node) => {
+            const altAttr = node.attributes.find((attr) => attr.type === 'JSXAttribute' && attr.name.type === 'JSXIdentifier' && attr.name.name === 'alt');
+            if (!altAttr || altAttr.type !== 'JSXAttribute')
+                return null;
+            if (!altAttr.value)
+                return '';
+            if (altAttr.value.type === 'Literal' && typeof altAttr.value.value === 'string') {
+                return altAttr.value.value;
+            }
+            return null; // Dynamic value
+        };
+        /**
+         * Check for aria-label or aria-labelledby
+         */
+        const hasAriaLabel = (node) => {
+            if (!allowAriaLabel && !allowAriaLabelledby)
+                return false;
+            return node.attributes.some((attr) => {
+                if (attr.type !== 'JSXAttribute' || attr.name.type !== 'JSXIdentifier')
+                    return false;
+                return ((allowAriaLabel && attr.name.name === 'aria-label') ||
+                    (allowAriaLabelledby && attr.name.name === 'aria-labelledby'));
+            });
+        };
+        /**
+         * Extract context about the image
+         */
+        const getImageContext = (node) => {
+            const srcAttr = node.attributes.find((attr) => attr.type === 'JSXAttribute' && attr.name.type === 'JSXIdentifier' && attr.name.name === 'src');
+            let src;
+            if (srcAttr && srcAttr.type === 'JSXAttribute' && srcAttr.value?.type === 'Literal') {
+                src = String(srcAttr.value.value);
+            }
+            return {
+                src,
+                usage: 'Content image', // Could be enhanced to detect context
+                surroundingText: 'Unknown context',
+            };
+        };
+        /**
+         * Suggest alt text based on context
+         */
+        const suggestAltText = (imageContext) => {
+            const suggestions = [];
+            if (imageContext.src) {
+                // Extract filename-based suggestion
+                const filename = imageContext.src.split('/').pop()?.replace(/\.[^.]+$/, '');
+                if (filename) {
+                    suggestions.push(filename.replace(/-|_/g, ' '));
+                }
+            }
+            suggestions.push('Descriptive text about the image');
+            suggestions.push('Product image showing [description]');
+            return suggestions;
+        };
+        return {
+            JSXOpeningElement(node) {
+                // Check if this is an img element
+                if (node.name.type !== 'JSXIdentifier' || node.name.name !== 'img') {
+                    return;
+                }
+                // Check if has alt or aria-label
+                if (hasAltAttribute(node)) {
+                    const altValue = getAltValue(node);
+                    // If alt value is null, it means alt={undefined} or alt={variable} - still missing
+                    if (altValue === null) {
+                        // alt attribute exists but value is dynamic/undefined - treat as missing
+                    }
+                    else if (altValue === '') {
+                        // Empty alt is valid for decorative images, but we can suggest verification
+                        return;
+                    }
+                    else {
+                        // Has valid alt text
+                        return;
+                    }
+                }
+                if (hasAriaLabel(node)) {
+                    return; // Has aria-label as alternative
+                }
+                // Missing alt text
+                const imageContext = getImageContext(node);
+                const suggestions = suggestAltText(imageContext);
+                context.report({
+                    node,
+                    messageId: 'missingAlt',
+                    data: {
+                        affectedUsers: '8% of users',
+                        wcagLevel: 'A',
+                        suggestion: suggestions[0] || 'Descriptive text',
+                    },
+                    suggest: [
+                        {
+                            messageId: 'addDescriptiveAlt',
+                            fix: (fixer) => {
+                                // Add alt with placeholder
+                                const lastAttr = node.attributes[node.attributes.length - 1];
+                                const insertAfter = lastAttr || node.name;
+                                return fixer.insertTextAfter(insertAfter, ' alt="TODO: Add descriptive text"');
+                            },
+                        },
+                        {
+                            messageId: 'useEmptyAlt',
+                            fix: (fixer) => {
+                                const lastAttr = node.attributes[node.attributes.length - 1];
+                                const insertAfter = lastAttr || node.name;
+                                return fixer.insertTextAfter(insertAfter, ' alt=""');
+                            },
+                        },
+                    ],
+                });
+            },
+        };
+    },
+});

package/src/rules/anchor-ambiguous-text.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Copyright (c) 2025 Ofri Peretz
+ * Licensed under the MIT License. Use of this source code is governed by the
+ * MIT license that can be found in the LICENSE file.
+ */
+/**
+ * ESLint Rule: anchor-ambiguous-text
+ * Enforce that anchor text is not ambiguous
+ *
+ * @see https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/blob/main/docs/rules/anchor-ambiguous-text.md
+ */
+import type { TSESLint } from '@interlace/eslint-devkit';
+type Options = {
+    words?: string[];
+};
+type RuleOptions = [Options?];
+export declare const anchorAmbiguousText: TSESLint.RuleModule<"ambiguousText", RuleOptions, unknown, TSESLint.RuleListener> & {
+    name: string;
+};
+export {};