@ngbracket/a11y-devtools 0.2.0 → 0.3.0

package/README.md

@@ -1,25 +1,34 @@
 # @ngbracket/a11y-devtools
 
 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
-(`@axe-core/react`, `axe-mode`, TanStack a11y) structurally can't do.
+back to **the component that rendered it** — so you get
+`♿ UserCardComponent — 2 issue(s)`, not a wall of CSS selectors.
 
-Report `♿ UserCardComponent — 2 issue(s)` instead of a wall of CSS selectors.
+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.
 
 ## Status
 
-Ships attribution + axe scan + grouped console reporter + the dev-only provider
-+ the visual in-app overlay (severity-coloured highlights, click-to-scroll).
+Ships attribution — component **and** directive-level — + axe scan + grouped
+console reporter (with a summary line) + the dev-only provider + the visual in-app
+overlay (severity-coloured highlights, click-to-scroll).
 
 ## How the attribution works
 
 Angular publishes debug helpers on the `window.ng` global in dev mode.
 `getOwningComponent(node)` returns the component whose view contains a DOM node,
-so any axe-flagged element resolves to its owning component. These helpers exist
-**only in dev builds** — which is exactly right: the tool is dev-only, and the
-global's absence in prod is the signal to no-op.
+so any axe-flagged element resolves to its owning component; `getDirectives(node)`
+adds the directives applied to that node — including those pulled in via
+`hostDirectives` — which are the runtime cases a static ESLint pass can't see.
+These helpers exist **only in dev builds** — which is exactly right: the tool is
+dev-only, and the global's absence in prod is the signal to no-op.
 
 ## Install
 
@@ -52,9 +61,24 @@ 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
 });
 ```
 
+Findings are grouped by owning component, led by a summary line, and each node's
+directives are shown inline:
+
+```text
+♿ a11y-devtools: 2 issue(s) across 1 component(s)
+♿ UserCardComponent — 2 issue(s)
+    critical · image-alt: Images must have alternative text [via TooltipDirective]
+      img
+      https://dequeuniversity.com/rules/axe/4.13/image-alt
+    serious · color-contrast: Elements must meet minimum contrast
+      button.save
+      https://dequeuniversity.com/rules/axe/4.13/color-contrast
+```
+
 You can also scan on demand:
 
 ```ts
@@ -64,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.
@@ -87,9 +131,7 @@ npm run build   # tsc -> dist/ (ESM + .d.ts)
 
 ## Roadmap
 
-- **`host` / `hostDirectives` a11y** via `getDirectives(el)` — the runtime cases
-  a static ESLint pass can't see.
-- Per-component filtering and a violation count badge.
+- Per-component filtering and a violation-count badge.
 
-Done: attribution · axe scan · grouped console reporter · dev-only provider ·
-in-app overlay · CI prod-weight guard.
+Done: component attribution · directive / `hostDirectives` attribution · axe scan ·
+grouped console reporter · dev-only provider · in-app overlay · CI prod-weight guard.

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.0",
+  "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": {