@ngbracket/a11y-devtools 0.1.0

package/README.md

@@ -0,0 +1,96 @@
+# @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.
+
+Report `♿ UserCardComponent — 2 issue(s)` instead of a wall of CSS selectors.
+
+Part of the `@ngbracket` Angular tooling family. See
+[`docs/findings.md`](docs/findings.md) for the research and scope.
+
+## Status
+
+Ships attribution + axe scan + grouped console reporter + 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.
+
+## Install
+
+```bash
+npm i -D @ngbracket/a11y-devtools
+```
+
+Peer deps: `@angular/core >=18`, `rxjs >=7`.
+
+## Usage
+
+```ts
+// app.config.ts (dev configuration)
+import { provideA11yDevtools } from '@ngbracket/a11y-devtools';
+
+export const appConfig = {
+  providers: [
+    // ...your providers
+    provideA11yDevtools(),
+  ],
+};
+```
+
+It rescans whenever the app settles (zoneless-aware, via `ApplicationRef.isStable`)
+and logs violations grouped by owning component. Options:
+
+```ts
+provideA11yDevtools({
+  root: () => document.querySelector('main')!, // scan scope; default document
+  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
+});
+```
+
+You can also scan on demand:
+
+```ts
+import { runA11yScan, scan } from '@ngbracket/a11y-devtools';
+
+const findings = await runA11yScan();      // scan + grouped log
+const raw = await scan(document.body);     // findings only
+```
+
+## Production weight
+
+In production `provideA11yDevtools()` is a **no-op** and axe-core is never loaded.
+axe-core is a **dynamic import**, so it lands in a lazy chunk that prod never
+fetches, and the package is `sideEffects: false` so an unused import tree-shakes
+away entirely. For a hard guarantee, include the provider only in your dev
+bootstrap config (e.g. behind `isDevMode()`).
+
+This is **enforced in CI**: `src/testing/prod-weight.spec.ts` bundles the entry
+with esbuild and walks the module graph — axe-core must be reachable *only*
+through a dynamic import, never a static one. Turning `import('axe-core')` into a
+static import (or adding a top-level side effect) fails the build.
+
+## Develop
+
+```bash
+npm install --legacy-peer-deps
+npm test        # vitest + jsdom + Angular TestBed (real axe)
+npm run build   # tsc -> dist/ (ESM + .d.ts)
+```
+
+## Roadmap
+
+- **`host` / `hostDirectives` a11y** via `getDirectives(el)` — the runtime cases
+  the item-2 lint plugin can't see statically.
+- 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.

package/dist/attribution.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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.
+ *
+ * Angular's debug helpers are NOT public named exports of `@angular/core`; they
+ * are methods on the `window.ng` global published in dev mode
+ * (`publishDefaultGlobalUtils`). `getComponent` resolves a component's host
+ * element to its instance; `getOwningComponent` resolves any inner node to the
+ * component whose view contains it. Try host first, then owner. The global's
+ * absence is the non-dev signal — callers should treat `null` as "not available".
+ */
+export interface NgDebugGlobal {
+    getComponent(element: Element): unknown;
+    getOwningComponent(element: Element | object): unknown;
+}
+export declare function ngDebug(): NgDebugGlobal | undefined;
+export declare function resolveOwningComponentName(node: Element): string | null;

package/dist/attribution.js

@@ -0,0 +1,15 @@
+export function ngDebug() {
+    return globalThis.ng;
+}
+function nameOf(instance) {
+    if (!instance || typeof instance !== 'object')
+        return null;
+    return instance.constructor.name ?? null;
+}
+export function resolveOwningComponentName(node) {
+    const ng = ngDebug();
+    if (!ng)
+        return null;
+    const component = ng.getComponent(node) ?? ng.getOwningComponent(node);
+    return nameOf(component);
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { provideA11yDevtools, type A11yDevtoolsOptions } from './provider';
+export { runA11yScan, type RunOptions } from './runner';
+export { scan, type A11yFinding, type Impact } from './scan';
+export { logFindings, type Logger } from './report';
+export { resolveOwningComponentName, ngDebug, type NgDebugGlobal } from './attribution';
+export { createOverlay, OVERLAY_ATTR, OVERLAY_EXCLUDE_SELECTOR, type A11yOverlay, type OverlayOptions, } from './overlay';

package/dist/index.js

@@ -0,0 +1,6 @@
+export { provideA11yDevtools } from './provider';
+export { runA11yScan } from './runner';
+export { scan } from './scan';
+export { logFindings } from './report';
+export { resolveOwningComponentName, ngDebug } from './attribution';
+export { createOverlay, OVERLAY_ATTR, OVERLAY_EXCLUDE_SELECTOR, } from './overlay';

package/dist/overlay.d.ts

@@ -0,0 +1,29 @@
+import type { A11yFinding } from './scan';
+/**
+ * Attribute marking the overlay's own DOM. `scan()` excludes anything under it
+ * so the tool never reports violations against its own highlights.
+ */
+export declare const OVERLAY_ATTR = "data-ngb-a11y-overlay";
+/** Selector form of {@link OVERLAY_ATTR}, passed to axe as an exclude. */
+export declare const OVERLAY_EXCLUDE_SELECTOR = "[data-ngb-a11y-overlay]";
+export interface A11yOverlay {
+    /** Draw a highlight over each finding's node, replacing the previous set. */
+    render(findings: A11yFinding[]): void;
+    /** Remove all highlights but keep the overlay live. */
+    clear(): void;
+    /** Tear down: remove the container and detach scroll/resize listeners. */
+    destroy(): void;
+}
+export interface OverlayOptions {
+    /** Document to render into. Defaults to the global `document`. */
+    document?: Document;
+}
+/**
+ * A dev-only visual overlay: absolutely-positioned boxes drawn over the nodes
+ * axe flagged, coloured by impact, click-to-scroll to the offending element.
+ * Plain DOM — no Angular component — so it stays framework-agnostic, carries no
+ * change-detection cost, and its own DOM is trivially excluded from scans via
+ * {@link OVERLAY_ATTR}. Boxes reposition on scroll/resize so they track their
+ * targets as the page moves.
+ */
+export declare function createOverlay(options?: OverlayOptions): A11yOverlay;

package/dist/overlay.js

@@ -0,0 +1,148 @@
+/**
+ * Attribute marking the overlay's own DOM. `scan()` excludes anything under it
+ * so the tool never reports violations against its own highlights.
+ */
+export const OVERLAY_ATTR = 'data-ngb-a11y-overlay';
+/** Selector form of {@link OVERLAY_ATTR}, passed to axe as an exclude. */
+export const OVERLAY_EXCLUDE_SELECTOR = `[${OVERLAY_ATTR}]`;
+/** Border/label colour per axe impact. `null` impact falls back to `none`. */
+const IMPACT_COLOR = {
+    critical: '#d32029',
+    serious: '#e8710a',
+    moderate: '#c9a227',
+    minor: '#3b7dd8',
+    none: '#8a8a8a',
+};
+function colorFor(impact) {
+    return IMPACT_COLOR[impact ?? 'none'];
+}
+/**
+ * A dev-only visual overlay: absolutely-positioned boxes drawn over the nodes
+ * axe flagged, coloured by impact, click-to-scroll to the offending element.
+ * Plain DOM — no Angular component — so it stays framework-agnostic, carries no
+ * change-detection cost, and its own DOM is trivially excluded from scans via
+ * {@link OVERLAY_ATTR}. Boxes reposition on scroll/resize so they track their
+ * targets as the page moves.
+ */
+export function createOverlay(options = {}) {
+    const doc = options.document ?? document;
+    const container = doc.createElement('div');
+    container.setAttribute(OVERLAY_ATTR, '');
+    Object.assign(container.style, {
+        position: 'fixed',
+        inset: '0',
+        pointerEvents: 'none', // pass clicks through; individual boxes opt back in
+        zIndex: '2147483646',
+    });
+    doc.body.appendChild(container);
+    let highlights = [];
+    const reposition = () => {
+        for (const { target, box } of highlights) {
+            positionBox(box, target);
+        }
+    };
+    // rAF-throttle so a stream of scroll events collapses to one layout read.
+    const raf = doc.defaultView?.requestAnimationFrame?.bind(doc.defaultView);
+    let scheduled = false;
+    const onViewportChange = () => {
+        if (!raf) {
+            reposition();
+            return;
+        }
+        if (scheduled)
+            return;
+        scheduled = true;
+        raf(() => {
+            scheduled = false;
+            reposition();
+        });
+    };
+    const win = doc.defaultView;
+    win?.addEventListener('scroll', onViewportChange, { passive: true, capture: true });
+    win?.addEventListener('resize', onViewportChange, { passive: true });
+    function clear() {
+        for (const { box } of highlights)
+            box.remove();
+        highlights = [];
+    }
+    function render(findings) {
+        clear();
+        for (const finding of findings) {
+            const target = resolveTarget(doc, finding.target);
+            if (!target)
+                continue; // node gone since the scan (e.g. re-rendered)
+            const box = buildBox(doc, finding);
+            box.addEventListener('click', () => flashAndScroll(target, box));
+            container.appendChild(box);
+            positionBox(box, target);
+            highlights.push({ finding, target, box });
+        }
+    }
+    function destroy() {
+        clear();
+        win?.removeEventListener('scroll', onViewportChange, { capture: true });
+        win?.removeEventListener('resize', onViewportChange);
+        container.remove();
+    }
+    return { render, clear, destroy };
+}
+/** Resolve a finding's target selector to a node, tolerating a bad selector. */
+function resolveTarget(doc, target) {
+    try {
+        return doc.querySelector(target);
+    }
+    catch {
+        return null;
+    }
+}
+function buildBox(doc, finding) {
+    const color = colorFor(finding.impact);
+    const box = doc.createElement('div');
+    box.setAttribute('data-impact', finding.impact ?? 'none');
+    box.title = `${finding.id}: ${finding.help}`;
+    Object.assign(box.style, {
+        position: 'fixed',
+        boxSizing: 'border-box',
+        border: `2px solid ${color}`,
+        borderRadius: '2px',
+        background: `${color}1a`, // ~10% alpha
+        pointerEvents: 'auto',
+        cursor: 'pointer',
+    });
+    const label = doc.createElement('span');
+    label.textContent = finding.component
+        ? `${finding.component} · ${finding.id}`
+        : finding.id;
+    Object.assign(label.style, {
+        position: 'absolute',
+        top: '0',
+        left: '0',
+        transform: 'translateY(-100%)',
+        padding: '1px 4px',
+        font: '11px/1.4 ui-monospace, monospace',
+        color: '#fff',
+        background: color,
+        whiteSpace: 'nowrap',
+    });
+    box.appendChild(label);
+    return box;
+}
+/** Anchor `box` (position:fixed) over `target` using viewport coordinates. */
+function positionBox(box, target) {
+    const rect = target.getBoundingClientRect();
+    Object.assign(box.style, {
+        top: `${rect.top}px`,
+        left: `${rect.left}px`,
+        width: `${rect.width}px`,
+        height: `${rect.height}px`,
+    });
+}
+/** Scroll the offending node into view and briefly emphasise its highlight. */
+function flashAndScroll(target, box) {
+    target.scrollIntoView({ block: 'center', behavior: 'smooth' });
+    const original = box.style.boxShadow;
+    box.style.boxShadow = '0 0 0 4px rgba(255,255,255,0.6)';
+    box.ownerDocument.defaultView?.setTimeout(() => {
+        box.style.boxShadow = original;
+    }, 600);
+}

package/dist/provider.d.ts

@@ -0,0 +1,24 @@
+import { type EnvironmentProviders } from '@angular/core';
+import type { Logger } from './report';
+export interface A11yDevtoolsOptions {
+    /** Element/Document to scan. Defaults to `document`. */
+    root?: () => Element | Document;
+    /** Log grouped findings to the console. Default true. */
+    log?: boolean;
+    /** Sink for reporting; defaults to `console`. */
+    logger?: Logger;
+    /** Draw an in-app visual overlay over each flagged node. Default false. */
+    overlay?: boolean;
+    /** Quiet window after stabilization before scanning. Default 500ms. */
+    debounceMs?: number;
+}
+/**
+ * Dev-only in-app accessibility auditing. Rescans whenever the application
+ * settles (zoneless-aware, via `ApplicationRef.isStable`) and reports each
+ * violation against the component that rendered it.
+ *
+ * In production this is a no-op and axe-core is never loaded, so it carries no
+ * runtime weight. For a hard guarantee, include the provider only in your dev
+ * bootstrap config.
+ */
+export declare function provideA11yDevtools(options?: A11yDevtoolsOptions): EnvironmentProviders;

package/dist/provider.js

@@ -0,0 +1,44 @@
+import { ApplicationRef, DestroyRef, inject, isDevMode, makeEnvironmentProviders, provideEnvironmentInitializer, } from '@angular/core';
+import { debounceTime, filter } from 'rxjs';
+import { runA11yScan } from './runner';
+import { createOverlay } from './overlay';
+/**
+ * Dev-only in-app accessibility auditing. Rescans whenever the application
+ * settles (zoneless-aware, via `ApplicationRef.isStable`) and reports each
+ * violation against the component that rendered it.
+ *
+ * In production this is a no-op and axe-core is never loaded, so it carries no
+ * runtime weight. For a hard guarantee, include the provider only in your dev
+ * bootstrap config.
+ */
+export function provideA11yDevtools(options = {}) {
+    if (!isDevMode()) {
+        return makeEnvironmentProviders([]);
+    }
+    const { root, log = true, logger, overlay = false, debounceMs = 500 } = options;
+    return makeEnvironmentProviders([
+        provideEnvironmentInitializer(() => {
+            const appRef = inject(ApplicationRef);
+            const destroyRef = inject(DestroyRef);
+            const overlayView = overlay ? createOverlay() : undefined;
+            let scanning = false;
+            const subscription = appRef.isStable
+                .pipe(filter((stable) => stable), debounceTime(debounceMs))
+                .subscribe(() => {
+                if (scanning)
+                    return; // don't stack rescans while one is in flight
+                scanning = true;
+                runA11yScan(root?.(), { log, logger })
+                    .then((findings) => overlayView?.render(findings))
+                    .catch(() => undefined)
+                    .finally(() => {
+                    scanning = false;
+                });
+            });
+            destroyRef.onDestroy(() => {
+                subscription.unsubscribe();
+                overlayView?.destroy();
+            });
+        }),
+    ]);
+}

package/dist/report.d.ts

@@ -0,0 +1,14 @@
+import type { A11yFinding } from './scan';
+/** Minimal console-shaped sink, so reporting is testable without the real console. */
+export interface Logger {
+    groupCollapsed(label: string): void;
+    groupEnd(): void;
+    warn(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+}
+/**
+ * Log findings grouped by the component that owns them — the readable form the
+ * attribution makes possible ("♿ UserCardComponent — 2 issues" beats a list of
+ * CSS selectors).
+ */
+export declare function logFindings(findings: A11yFinding[], logger?: Logger): void;

package/dist/report.js

@@ -0,0 +1,27 @@
+/**
+ * Log findings grouped by the component that owns them — the readable form the
+ * attribution makes possible ("♿ UserCardComponent — 2 issues" beats a list of
+ * CSS selectors).
+ */
+export function logFindings(findings, logger = console) {
+    if (findings.length === 0) {
+        logger.info('♿ a11y-devtools: no violations found');
+        return;
+    }
+    const byComponent = new Map();
+    for (const finding of findings) {
+        const key = finding.component ?? '(unknown component)';
+        const bucket = byComponent.get(key);
+        if (bucket)
+            bucket.push(finding);
+        else
+            byComponent.set(key, [finding]);
+    }
+    for (const [component, items] of byComponent) {
+        logger.groupCollapsed(`♿ ${component} — ${items.length} issue(s)`);
+        for (const finding of items) {
+            logger.warn(`${finding.impact ?? 'n/a'} · ${finding.id}: ${finding.help}`, `\n  ${finding.target}\n  ${finding.helpUrl}`);
+        }
+        logger.groupEnd();
+    }
+}

package/dist/runner.d.ts

@@ -0,0 +1,10 @@
+import { type A11yFinding } from './scan';
+import { type Logger } from './report';
+export interface RunOptions {
+    /** Log grouped findings to the console. Default true. */
+    log?: boolean;
+    /** Sink for reporting; defaults to `console`. */
+    logger?: Logger;
+}
+/** Scan `root`, optionally report, and return the findings. */
+export declare function runA11yScan(root?: Element | Document, options?: RunOptions): Promise<A11yFinding[]>;

package/dist/runner.js

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

package/dist/scan.d.ts

@@ -0,0 +1,22 @@
+import type { RunOptions } from 'axe-core';
+export type Impact = 'minor' | 'moderate' | 'serious' | 'critical' | null;
+/** One axe violation node, enriched with the component that rendered it. */
+export interface A11yFinding {
+    /** axe rule id, e.g. `image-alt`. */
+    id: string;
+    impact: Impact;
+    help: string;
+    helpUrl: string;
+    /** Owning component name, or null when attribution isn't available (prod). */
+    component: string | null;
+    /** CSS selector axe reported for the node. */
+    target: string;
+    html: string;
+}
+/**
+ * Run axe over `root` and return findings enriched with owning component names.
+ * axe-core is loaded via dynamic import so a prod build never pulls it into the
+ * main bundle (the provider also no-ops outside dev mode). Concurrent calls are
+ * serialized because axe cannot run more than once at a time.
+ */
+export declare function scan(root?: Element | Document, options?: RunOptions): Promise<A11yFinding[]>;

package/dist/scan.js

@@ -0,0 +1,46 @@
+import { resolveOwningComponentName } from './attribution';
+import { OVERLAY_EXCLUDE_SELECTOR } from './overlay';
+// axe-core is a singleton and throws if a run starts while another is in flight.
+// Chain runs so overlapping callers (e.g. rapid rescans) serialize safely.
+let runChain = Promise.resolve();
+/**
+ * Run axe over `root` and return findings enriched with owning component names.
+ * axe-core is loaded via dynamic import so a prod build never pulls it into the
+ * main bundle (the provider also no-ops outside dev mode). Concurrent calls are
+ * serialized because axe cannot run more than once at a time.
+ */
+export function scan(root = document, options) {
+    const result = runChain.then(() => runAxeOnce(root, options));
+    runChain = result.catch(() => undefined);
+    return result;
+}
+async function runAxeOnce(root, options) {
+    const axe = (await import('axe-core')).default;
+    // Scan within `root` but never flag the overlay's own highlights.
+    const context = { include: root, exclude: [OVERLAY_EXCLUDE_SELECTOR] };
+    const results = await axe.run(context, options ?? {});
+    const doc = root instanceof Document ? root : (root.ownerDocument ?? document);
+    const findings = [];
+    for (const violation of results.violations) {
+        for (const node of violation.nodes) {
+            const target = Array.isArray(node.target) ? String(node.target[0]) : String(node.target);
+            let element = null;
+            try {
+                element = doc.querySelector(target);
+            }
+            catch {
+                element = null;
+            }
+            findings.push({
+                id: violation.id,
+                impact: (violation.impact ?? null),
+                help: violation.help,
+                helpUrl: violation.helpUrl,
+                component: element ? resolveOwningComponentName(element) : null,
+                target,
+                html: node.html,
+            });
+        }
+    }
+    return findings;
+}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@ngbracket/a11y-devtools",
+  "version": "0.1.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",
+  "contributors": [
+    "Lara Sanz"
+  ],
+  "homepage": "https://ngbracket.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ngbracket/a11y-devtools"
+  },
+  "keywords": [
+    "angular",
+    "accessibility",
+    "a11y",
+    "devtools",
+    "axe-core",
+    "axe",
+    "ngbracket"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "axe-core": "^4.13.0"
+  },
+  "peerDependencies": {
+    "@angular/core": ">=18.0.0",
+    "rxjs": ">=7.0.0"
+  },
+  "devDependencies": {
+    "@analogjs/vite-plugin-angular": "^2.7.2",
+    "@analogjs/vitest-angular": "^2.7.2",
+    "@angular/build": "^22.1.7",
+    "@angular/common": "^22.1.5",
+    "@angular/compiler": "^22.1.5",
+    "@angular/compiler-cli": "^22.1.5",
+    "@angular/core": "^22.1.5",
+    "@angular/platform-browser": "^22.1.5",
+    "@angular/platform-browser-dynamic": "^22.1.5",
+    "@oxc-project/runtime": "^0.149.0",
+    "@types/node": "^26.5.0",
+    "jsdom": "^30.0.1",
+    "rxjs": "^7.8.2",
+    "tslib": "^2.8.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.11"
+  }
+}