[New] add support for Flat Config

This change adds support for ESLint's new Flat config system.
It maintains backwards compatibility with eslintrc style configs as well.

To achieve this, we're now dynamically creating four configs: two are the original `recommended` and `strict`, and the other two are the new `flat/recommended` and `flat/strict`.
The two `flat` ones are setup with the new config format, while the original two have the same options as before.

 Usage
 Legacy
```json
{
  "extends": ["plugin:jsx-a11y/recommended"]
}
```

 Flat
```js
import globals from 'globals';
import js from '@eslint/js';
import jsxA11y from 'eslint-plugin-jsx-a11y';

export default [
  js.configs.recommended,
  jsxA11y.flatConfigs.recommended,
  {
    files: ['**/*.{js,mjs,cjs,jsx,mjsx,ts,tsx,mtsx}'],
    languageOptions: {
      ecmaVersion: 'latest',
      sourceType: 'module',
      globals: globals.browser,
    },
    ignores: ['dist', 'eslint.config.js'],
    rules: {
      'no-unused-vars': 'warn',
      'jsx-a11y/anchor-ambiguous-text': 'warn',
      'jsx-a11y/anchor-is-valid': 'warn',
    },
  },
];
```

.eslintrc

@@ -7,6 +7,7 @@
   "ignorePatterns": [
     "lib/",
     "reports/",
+    "examples/",
   ],
   "parser": "@babel/eslint-parser",
   "plugins": [

.github/workflows/node-pretest.yml

@@ -38,3 +38,15 @@ jobs:
           node-version: 'lts/*'
           skip-ls-check: true
       - run: npm run posttest
+
+  examples:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ljharb/actions/node/install@main
+        name: 'nvm install lts/* && npm install'
+        with:
+          node-version: 'lts/*'
+          skip-ls-check: true
+      - run: npm run test:examples

README.md

@@ -60,7 +60,8 @@ yarn add eslint-plugin-jsx-a11y --dev
 
 **Note:** If you installed ESLint globally (using the `-g` flag in npm, or the `global` prefix in yarn) then you must also install `eslint-plugin-jsx-a11y` globally.
 
-## Usage
+<a id="usage"></a>
+## Usage - Legacy Config (`.eslintrc`)
 
 Add `jsx-a11y` to the plugins section of your `.eslintrc` configuration file. You can omit the `eslint-plugin-` prefix:
 
@@ -109,6 +110,94 @@ Add `plugin:jsx-a11y/recommended` or `plugin:jsx-a11y/strict` in `extends`:
 }
 ```
 
+## Usage - Flat Config (`eslint.config.js`)
+
+The default export of `eslint-plugin-jsx-a11y` is a plugin object.
+
+```js
+const jsxA11y = require('eslint-plugin-jsx-a11y');
+
+module.exports = [
+  …
+  {
+    files: ['**/*.{js,mjs,cjs,jsx,mjsx,ts,tsx,mtsx}'],
+    plugins: {
+      'jsx-a11y': jsxA11y,
+    },
+    languageOptions: {
+      parserOptions: {
+        ecmaFeatures: {
+          jsx: true,
+        },
+      },
+    },
+    rules: {
+      // ... any rules you want
+      'jsx-a11y/alt-text': 'error',
+    },
+    // ... others are omitted for brevity
+  },
+  …
+];
+```
+
+### Shareable Configs
+
+There are two shareable configs, provided by the plugin.
+
+- `flatConfigs.recommended`
+- `flatConfigs.strict`
+
+#### CJS
+
+```js
+const jsxA11y = require('eslint-plugin-jsx-a11y');
+
+export default [
+  jsxA11y.flatConfigs.recommended,
+  {
+    // Your additional configs and overrides
+  },
+];
+```
+
+#### ESM
+
+```js
+import jsxA11y from 'eslint-plugin-jsx-a11y';
+
+export default [
+  jsxA11y.flatConfigs.recommended,
+  {
+    // Your additional configs and overrides
+  },
+];
+```
+
+**Note**: Our shareable config do configure `files` or [`languageOptions.globals`](https://eslint.org/docs/latest/user-guide/configuring/configuration-files-new#configuration-objects).
+For most of the cases, you probably want to configure some of these properties yourself.
+
+```js
+const jsxA11yRecommended = require('eslint-plugin-jsx-a11y');
+const globals = require('globals');
+
+module.exports = [
+  …
+  {
+    files: ['**/*.{js,mjs,cjs,jsx,mjsx,ts,tsx,mtsx}'],
+    ...jsxA11y.flatConfigs.recommended,
+    languageOptions: {
+      ...jsxA11y.flatConfigs.recommended.languageOptions,
+      globals: {
+        ...globals.serviceworker,
+        ...globals.browser,
+      },
+    },
+  },
+  …
+];
+```
+
 #### Component Mapping
 
 To enable your custom components to be checked as DOM elements, you can set global settings in your configuration file by mapping each custom component name to a DOM element type.
@@ -124,7 +213,7 @@ For example, if you set the `polymorphicPropName` setting to `as` then this elem
 
 will be evaluated as an `h3`. If no `polymorphicPropName` is set, then the component will be evaluated as `Box`.
 
-⚠️  Polymorphic components can make code harder to maintain; please use this feature with caution.
+⚠️ Polymorphic components can make code harder to maintain; please use this feature with caution.
 
 ## Supported Rules
 

examples/flat-cjs/eslint.config.cjs

@@ -0,0 +1,22 @@
+const globals = require('globals');
+const js = require('@eslint/js');
+const jsxA11y = require('eslint-plugin-jsx-a11y');
+
+module.exports = [
+  js.configs.recommended,
+  jsxA11y.flatConfigs.recommended,
+  {
+    files: ['**/*.{js,mjs,cjs,jsx,mjsx,ts,tsx,mtsx}'],
+    languageOptions: {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+      globals: globals.browser,
+    },
+    ignores: ['dist', 'eslint.config.cjs'],
+    rules: {
+      'no-unused-vars': 'off',
+      'jsx-a11y/anchor-ambiguous-text': 'warn',
+      'jsx-a11y/anchor-is-valid': 'warn',
+    },
+  },
+];

examples/flat-cjs/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Vite + React</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>

examples/flat-cjs/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "flat-cjs",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "lint": "cross-env ESLINT_USE_FLAT_CONFIG=true eslint . --report-unused-disable-directives"
+  },
+  "dependencies": {
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.5.0",
+    "cross-env": "^7.0.3",
+    "eslint": "^8.57.0",
+    "eslint-plugin-jsx-a11y": "file:../..",
+    "globals": "^15.6.0"
+  }
+}

examples/flat-cjs/src/App.css

@@ -0,0 +1,42 @@
+#root {
+  max-width: 1280px;
+  margin: 0 auto;
+  padding: 2rem;
+  text-align: center;
+}
+
+.logo {
+  height: 6em;
+  padding: 1.5em;
+  will-change: filter;
+  transition: filter 300ms;
+}
+.logo:hover {
+  filter: drop-shadow(0 0 2em #646cffaa);
+}
+.logo.react:hover {
+  filter: drop-shadow(0 0 2em #61dafbaa);
+}
+
+@keyframes logo-spin {
+  from {
+    transform: rotate(0deg);
+  }
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  a:nth-of-type(2) .logo {
+    animation: logo-spin infinite 20s linear;
+  }
+}
+
+.card {
+  padding: 2em;
+}
+
+.read-the-docs {
+  color: #888;
+}

examples/flat-cjs/src/App.jsx

@@ -0,0 +1,36 @@
+import { useState } from 'react';
+import reactLogo from './assets/react.svg';
+import viteLogo from '/vite.svg';
+import './App.css';
+
+function App() {
+  const [count, setCount] = useState(0);
+
+  return (
+    <>
+      <div>
+        <a href="https://vitejs.dev" target="_blank">
+          <img src={viteLogo} className="logo" alt="Vite logo" />
+        </a>
+        <a href="https://react.dev" target="_blank">
+          <img src={reactLogo} className="logo react" alt="React logo" />
+        </a>
+        <a>click here</a>
+      </div>
+      <h1>Vite + React</h1>
+      <div className="card">
+        <button onClick={() => setCount((count) => count + 1)}>
+          count is {count}
+        </button>
+        <p>
+          Edit <code>src/App.jsx</code> and save to test HMR
+        </p>
+      </div>
+      <p className="read-the-docs">
+        Click on the Vite and React logos to learn more
+      </p>
+    </>
+  );
+}
+
+export default App;

examples/flat-cjs/src/index.css

@@ -0,0 +1,68 @@
+:root {
+  font-family: Inter, system-ui, Avenir, Helvetica, Arial, sans-serif;
+  line-height: 1.5;
+  font-weight: 400;
+
+  color-scheme: light dark;
+  color: rgba(255, 255, 255, 0.87);
+  background-color: #242424;
+
+  font-synthesis: none;
+  text-rendering: optimizeLegibility;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+a {
+  font-weight: 500;
+  color: #646cff;
+  text-decoration: inherit;
+}
+a:hover {
+  color: #535bf2;
+}
+
+body {
+  margin: 0;
+  display: flex;
+  place-items: center;
+  min-width: 320px;
+  min-height: 100vh;
+}
+
+h1 {
+  font-size: 3.2em;
+  line-height: 1.1;
+}
+
+button {
+  border-radius: 8px;
+  border: 1px solid transparent;
+  padding: 0.6em 1.2em;
+  font-size: 1em;
+  font-weight: 500;
+  font-family: inherit;
+  background-color: #1a1a1a;
+  cursor: pointer;
+  transition: border-color 0.25s;
+}
+button:hover {
+  border-color: #646cff;
+}
+button:focus,
+button:focus-visible {
+  outline: 4px auto -webkit-focus-ring-color;
+}
+
+@media (prefers-color-scheme: light) {
+  :root {
+    color: #213547;
+    background-color: #ffffff;
+  }
+  a:hover {
+    color: #747bff;
+  }
+  button {
+    background-color: #f9f9f9;
+  }
+}

examples/flat-cjs/src/main.jsx

@@ -0,0 +1,10 @@
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import App from './App.jsx'
+import './index.css'
+
+ReactDOM.createRoot(document.getElementById('root')).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+)

examples/flat-esm/eslint.config.js

@@ -0,0 +1,22 @@
+import globals from 'globals';
+import js from '@eslint/js';
+import jsxA11y from 'eslint-plugin-jsx-a11y';
+
+export default [
+  js.configs.recommended,
+  jsxA11y.flatConfigs.recommended,
+  {
+    files: ['**/*.{js,mjs,cjs,jsx,mjsx,ts,tsx,mtsx}'],
+    languageOptions: {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+      globals: globals.browser,
+    },
+    ignores: ['dist', 'eslint.config.js'],
+    rules: {
+      'no-unused-vars': 'off',
+      'jsx-a11y/anchor-ambiguous-text': 'warn',
+      'jsx-a11y/anchor-is-valid': 'warn',
+    },
+  },
+];

examples/flat-esm/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Vite + React</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>