@ngbracket/a11y-devtools 0.2.1 → 0.3.0

package/README.md

@@ -4,13 +4,13 @@ Dev-only, in-app accessibility auditing for Angular that maps each axe violation
 back to **the component that rendered it** — so you get
 `♿ UserCardComponent — 2 issue(s)`, not a wall of CSS selectors.
 
-The React axe tools in this space — [`@axe-core/react`](https://www.npmjs.com/package/@axe-core/react),
-[`axe-mode`](https://github.com/raunofreiberg/axe-mode), the
-[TanStack Devtools a11y plugin](https://tanstack.com/devtools/latest/docs/plugins/a11y)
-— report the DOM node (selector, HTML, rule id) and highlight it, but stop there:
-none tie a violation to the component that rendered it. This does, through
-Angular's **documented** dev debug API (`window.ng`) rather than private framework
-internals.
+The axe-based devtools in this space — [`@axe-core/react`](https://www.npmjs.com/package/@axe-core/react),
+[`axe-mode`](https://github.com/raunofreiberg/axe-mode), and
+[TanStack's a11y plugin](https://tanstack.com/devtools/latest/docs/plugins/a11y)
+(now cross-framework, with an Angular adapter too) — report the DOM node (selector,
+HTML, rule id) and highlight it, but we haven't seen one tie a violation back to the
+component that rendered it, by name. This does, through Angular's **documented** dev
+debug API (`window.ng`) rather than private framework internals.
 
 Part of the `@ngbracket` Angular tooling family.
 
@@ -61,6 +61,7 @@ provideA11yDevtools({
   log: true,           // grouped console output; default true
   overlay: true,       // in-app visual highlights over flagged nodes; default false
   debounceMs: 500,     // quiet window after stabilization before scanning
+  tags: ['wcag22aa'],  // scope the ruleset; default = axe-core's full ruleset
 });
 ```
 
@@ -87,6 +88,26 @@ const findings = await runA11yScan();      // scan + grouped log
 const raw = await scan(document.body);     // findings only
 ```
 
+`scan()` and `runA11yScan()` also take full axe-core run options as a second
+argument (`scan(root, { runOnly: … })`) for finer control than the provider's
+`tags`.
+
+## What it checks (and what it can't)
+
+Under the hood this is [axe-core](https://github.com/dequelabs/axe-core) — the
+scan runs axe's rules and enriches each violation with the owning component. By
+default it runs axe-core's full ruleset: the **machine-testable** rules across
+**WCAG 2.0, 2.1 and 2.2, Levels A & AA**, plus axe's *best-practice* rules. Scope
+it to a single conformance target with `tags` (e.g. `['wcag22aa']`) or
+`['wcag21aa', 'best-practice']`.
+
+Automated checks only cover the part of WCAG a machine can test — on the order of
+a third of the success criteria. Many WCAG 2.2 additions have **no automated rule
+at all** (target size 2.5.8, dragging 2.5.7, consistent help, redundant entry,
+accessible authentication), so a clean run is necessary, not sufficient — the rest
+needs keyboard, screen-reader and human testing. (WCAG 3.0 is still an early W3C
+draft with a different, non-final model; there's nothing to test against yet.)
+
 ## Production weight
 
 In production `provideA11yDevtools()` is a **no-op** and axe-core is never loaded.

package/dist/attribution.d.ts

@@ -1,6 +1,7 @@
 /**
  * Attribution core: given a DOM node that axe flagged, return the name of the
- * component responsible for it — the differentiator React overlay tools can't do.
+ * component responsible for it — the differentiator we haven't seen other axe
+ * overlay devtools do (they report the DOM node, not the owning component by name).
  *
  * Angular's debug helpers are NOT public named exports of `@angular/core`; they
  * are methods on the `window.ng` global published in dev mode

package/dist/provider.d.ts

@@ -11,6 +11,14 @@ export interface A11yDevtoolsOptions {
     overlay?: boolean;
     /** Quiet window after stabilization before scanning. Default 500ms. */
     debounceMs?: number;
+    /**
+     * Restrict the scan to specific axe tags, e.g. `['wcag22aa']` or
+     * `['wcag21aa', 'best-practice']`. Omit to run axe-core's default ruleset —
+     * the machine-testable rules across WCAG 2.0/2.1/2.2 (Levels A & AA) plus axe's
+     * best-practice rules. (For finer control, call `runA11yScan`/`scan` with full
+     * axe run options.)
+     */
+    tags?: string[];
 }
 /**
  * Dev-only in-app accessibility auditing. Rescans whenever the application

package/dist/provider.js

@@ -15,7 +15,10 @@ export function provideA11yDevtools(options = {}) {
     if (!isDevMode()) {
         return makeEnvironmentProviders([]);
     }
-    const { root, log = true, logger, overlay = false, debounceMs = 500 } = options;
+    const { root, log = true, logger, overlay = false, debounceMs = 500, tags } = options;
+    const axe = tags
+        ? { runOnly: { type: 'tag', values: tags } }
+        : undefined;
     return makeEnvironmentProviders([
         provideEnvironmentInitializer(() => {
             const appRef = inject(ApplicationRef);
@@ -28,7 +31,7 @@ export function provideA11yDevtools(options = {}) {
                 if (scanning)
                     return; // don't stack rescans while one is in flight
                 scanning = true;
-                runA11yScan(root?.(), { log, logger })
+                runA11yScan(root?.(), { log, logger, axe })
                     .then((findings) => overlayView?.render(findings))
                     .catch(() => undefined)
                     .finally(() => {

package/dist/runner.d.ts

@@ -1,3 +1,4 @@
+import type { RunOptions as AxeRunOptions } from 'axe-core';
 import { type A11yFinding } from './scan.js';
 import { type Logger } from './report.js';
 export interface RunOptions {
@@ -5,6 +6,14 @@ export interface RunOptions {
     log?: boolean;
     /** Sink for reporting; defaults to `console`. */
     logger?: Logger;
+    /**
+     * axe-core run options — use this to scope the ruleset, e.g.
+     * `{ runOnly: { type: 'tag', values: ['wcag22aa'] } }`. Omit to run axe-core's
+     * default ruleset: the machine-testable rules across WCAG 2.0/2.1/2.2 (Levels
+     * A & AA) plus axe's best-practice rules. (The provider exposes the common case
+     * as a friendlier `tags: string[]`.)
+     */
+    axe?: AxeRunOptions;
 }
 /** Scan `root`, optionally report, and return the findings. */
 export declare function runA11yScan(root?: Element | Document, options?: RunOptions): Promise<A11yFinding[]>;

package/dist/runner.js

@@ -2,7 +2,7 @@ import { scan } from './scan.js';
 import { logFindings } from './report.js';
 /** Scan `root`, optionally report, and return the findings. */
 export async function runA11yScan(root, options = {}) {
-    const findings = await scan(root ?? document);
+    const findings = await scan(root ?? document, options.axe);
     if (options.log !== false) {
         logFindings(findings, options.logger);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngbracket/a11y-devtools",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Dev-only in-app accessibility auditing for Angular that maps each axe violation back to the component that rendered it — the attribution React overlay tools can't do.",
   "license": "MIT",
   "author": "Duncan Faulkner",
@@ -42,6 +42,7 @@
     "build": "tsc -p tsconfig.json",
     "test": "vitest run",
     "test:watch": "vitest",
+    "demo:console": "vitest run --config vitest.demo.config.ts --disableConsoleIntercept",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {