@okent/accessibility-scanner-keyboard-plugin 0.1.0 → 0.1.2

package/README.md

@@ -3,7 +3,7 @@
 A plugin for [GitHub's accessibility scanner](https://github.com/github/accessibility-scanner)
 that walks the real Tab order of each page and reports the keyboard failures a
 rule engine inspecting the DOM at rest cannot see. It is a TypeScript port of
-the keyboard probe in [accessibility-tooling](../../), with the same rules, the
+the keyboard probe in accessibility-tooling, an ACR toolkit, with the same rules, the
 same thresholds, and the same refusal to treat a clean walk as a pass.
 
 | Rule | Criterion | Asserts |
@@ -44,7 +44,7 @@ Once the package is on the scanner's npm allowlist:
 - uses: github/accessibility-scanner@v3
   with:
     scans: |
-      ["axe", {"name": "keyboard-scan", "package": "@okent/accessibility-scanner-keyboard-plugin", "version": "0.1.0"}]
+      ["axe", {"name": "keyboard-scan", "package": "@okent/accessibility-scanner-keyboard-plugin", "version": "0.1.2"}]
 ```
 
 ### As a local plugin
@@ -110,12 +110,12 @@ into one summary finding.
 npm install
 npx playwright install chromium
 npm test          # unit tests for the walk analysis, plus an end-to-end run
-                  # against ../../tests/fixtures/demo.html
+                  # against test/fixtures/demo.html
 npm run build
 ```
 
-The end-to-end test asserts that every keyboard defect planted in the parent
-repository's fixture is found and that its control cases stay silent. The
+The end-to-end test asserts that every keyboard defect planted in the
+fixture is found and that its control cases stay silent. The
 fixture's header comment lists what is planted.
 
 ## License

package/dist/index.js

@@ -55,6 +55,11 @@ export default async function keyboardScan({ page, addFinding }) {
         console.warn(`[keyboard-scan] ${url}: ${notes.framesNotWalked} iframe(s) NOT walked; ` +
             `Tab order, traps and focus indicators inside them were not checked`);
     }
+    if (notes.modalScope) {
+        // A narrowed scan must never be silent: the rest of the page was not walked.
+        console.warn(`[keyboard-scan] ${url}: walk scoped to modal \`${notes.modalScope}\`; ` +
+            `everything outside it was NOT checked`);
+    }
     if (notes.dismissed) {
         console.warn(`[keyboard-scan] ${url}: Escape closed a container mid-walk, so the walk stopped there; ` +
             `reachability and focus visibility were not judged on this page`);

package/dist/src/probe.d.ts

@@ -18,6 +18,8 @@ export type ProbeNotes = {
     walkComplete: boolean;
     trapsFound: number;
     dismissed: boolean;
+    /** Selector of the modal the walk was scoped to, or null when it covered the page. */
+    modalScope: string | null;
 };
 /**
  * Walk the real Tab order of the page as it currently stands and report what

package/dist/src/probe.js

@@ -61,9 +61,14 @@ export async function probePage(page, cfg) {
         walkComplete: false,
         trapsFound: 0,
         dismissed: false,
+        modalScope: await evalScript(page, S.SCOPE),
     };
-    if (!cands.length)
+    if (!cands.length) {
+        // Nothing interactive to walk is a complete walk with nothing to judge,
+        // not an interrupted one.
+        notes.walkComplete = true;
         return { findings, notes };
+    }
     const n = cands.length;
     await evalScript(page, S.BLUR);
     const visited = new Set();
@@ -73,6 +78,7 @@ export async function probePage(page, cfg) {
     const shots = new Map();
     const traps = [];
     const escapedCycles = [];
+    const trapCycles = [];
     let dismissed = false;
     let walkComplete = false;
     let stray = 0;
@@ -90,6 +96,15 @@ export async function probePage(page, cfg) {
             }
         }
     };
+    // Move focus past an iframe or a trap and record the landing element as
+    // visited. Without this the next Tab leaves `nxt` without it ever being
+    // counted, so it is reported unreachable and skips its focus indicator check.
+    const stepTo = async (nxt) => {
+        await evalScript(page, S.FOCUS, nxt);
+        barriers.add(firstVisit.length);
+        await noteVisit(nxt);
+        seq = [];
+    };
     while (step < maxSteps) {
         step++;
         await page.keyboard.press('Tab');
@@ -124,6 +139,15 @@ export async function probePage(page, cfg) {
         const cyc = detectCycle(seq);
         if (!cyc || escapedCycles.some(e => sameMembers(e, cyc)))
             continue;
+        if (trapCycles.some(e => sameMembers(e, cyc))) {
+            // A second pass has walked back into a trap already reported. It is the
+            // same defect, so step past it rather than report it twice.
+            const again = nextFocusableAfter(cands, Math.max(...cyc), visited);
+            if (again === null)
+                break;
+            await stepTo(again);
+            continue;
+        }
         if (new Set(cyc).size >= n) {
             // The whole page cycling is wrap behaviour, not a trap.
             walkComplete = true;
@@ -137,9 +161,7 @@ export async function probePage(page, cfg) {
                 walkComplete = true;
                 break;
             }
-            await evalScript(page, S.FOCUS, nxt);
-            barriers.add(firstVisit.length);
-            seq = [];
+            await stepTo(nxt);
             continue;
         }
         // Candidate trap. The one exit a probe can honestly press is Escape: if
@@ -166,6 +188,7 @@ export async function probePage(page, cfg) {
             continue;
         }
         traps.push(cyc);
+        trapCycles.push(cyc);
         const anc = await evalScript(page, S.COMMON_ANCESTOR, cyc);
         const members = cyc.map(i => `\`${cands[i].selector}\``).join(', ');
         findings.push({
@@ -181,9 +204,7 @@ export async function probePage(page, cfg) {
         const nxt = nextFocusableAfter(cands, Math.max(...cyc), visited);
         if (nxt === null)
             break;
-        await evalScript(page, S.FOCUS, nxt);
-        barriers.add(firstVisit.length);
-        seq = [];
+        await stepTo(nxt);
     }
     notes.walkComplete = walkComplete;
     notes.trapsFound = traps.length;

package/dist/src/scripts.d.ts

@@ -1,6 +1,7 @@
 export declare const ENUMERATE: string;
 export declare const SHADOW_COUNT = "() => {\n\n  const queryAllComposed = (root, selector) => {\n    const out = [];\n    const visit = (node) => {\n      if (node.nodeType !== 1) return;\n      if (node.matches(selector)) out.push(node);\n      if (node.shadowRoot) {\n        for (const child of node.shadowRoot.children) visit(child);\n      }\n      for (const child of node.children) visit(child);\n    };\n    for (const child of root.children) visit(child);\n    if (root.shadowRoot) {\n      for (const child of root.shadowRoot.children) visit(child);\n    }\n    return out;\n  };\n\n  const countShadowRoots = (root) =>\n    queryAllComposed(root, '*').filter((el) => !!el.shadowRoot).length\n    + (root.shadowRoot ? 1 : 0);\n\n  return countShadowRoots(document.body);\n}";
 export declare const FRAME_COUNT = "() => {\n\n  const queryAllComposed = (root, selector) => {\n    const out = [];\n    const visit = (node) => {\n      if (node.nodeType !== 1) return;\n      if (node.matches(selector)) out.push(node);\n      if (node.shadowRoot) {\n        for (const child of node.shadowRoot.children) visit(child);\n      }\n      for (const child of node.children) visit(child);\n    };\n    for (const child of root.children) visit(child);\n    if (root.shadowRoot) {\n      for (const child of root.shadowRoot.children) visit(child);\n    }\n    return out;\n  };\n\n  const countFrames = (root) => queryAllComposed(root, 'iframe,frame').length;\n\n  return countFrames(document.body);\n}";
+export declare const SCOPE = "() => (window.__kbProbe && window.__kbProbe.scope) || null";
 export declare const ACTIVE = "() => {\n\n  const deepActiveElement = (doc) => {\n    let el = doc.activeElement;\n    while (el && el.shadowRoot && el.shadowRoot.activeElement) {\n      el = el.shadowRoot.activeElement;\n    }\n    return el;\n  };\n\n  const p = window.__kbProbe || { els: [] };\n  const ae = deepActiveElement(document);\n  const wrapped = !ae || ae === document.body || ae === document.documentElement;\n  return { idx: wrapped ? -1 : p.els.indexOf(ae), wrapped: wrapped };\n}";
 export declare const RECT = "(i) => {\n  const el = window.__kbProbe.els[i];\n  const r = el.getBoundingClientRect();\n  return { x: r.x, y: r.y, w: r.width, h: r.height,\n           sx: window.scrollX, sy: window.scrollY,\n           vw: window.innerWidth, vh: window.innerHeight };\n}";
 export declare const ALL_VISIBLE = "(idxs) => {\n  const p = window.__kbProbe || { els: [] };\n  return idxs.every(i => {\n    const el = p.els[i];\n    if (!el || !el.isConnected) return false;\n    const cs = getComputedStyle(el);\n    if (cs.display === 'none' || cs.visibility !== 'visible') return false;\n    const r = el.getBoundingClientRect();\n    return r.width >= 2 && r.height >= 2;\n  });\n}";

package/dist/src/scripts.js

@@ -107,10 +107,12 @@ const IFRAME_COUNT = `
 `;
 export const ENUMERATE = `() => {
 ${QUERY_ALL}${COMPOSED_ANCESTRY}${COMPOSED_SELECTOR}${SHADOW_ROOT_COUNT}
-  // dialog:modal is the well-behaved case; role alone is not proof of
-  // modality, but it is what a hand-rolled widget tends to expose instead of
-  // a real <dialog>. The first visible match wins.
-  const MODAL_SEL = 'dialog:modal, [role="dialog"], [role="alertdialog"], [aria-modal="true"]';
+  // Only a dialog that is actually modal narrows the walk: a <dialog> opened
+  // with showModal() (:modal), or one that declares aria-modal="true". A
+  // visible role="dialog" alone is routinely a cookie banner or chat widget
+  // sitting beside the page; scoping to it would silently drop the rest of
+  // the page from the scan. The first visible match wins.
+  const MODAL_SEL = 'dialog:modal, [role="dialog"][aria-modal="true"], [role="alertdialog"][aria-modal="true"]';
   let modal = null;
   for (const el of queryAllComposed(document.body, MODAL_SEL)) {
     const mcs = getComputedStyle(el);
@@ -146,7 +148,8 @@ ${QUERY_ALL}${COMPOSED_ANCESTRY}${COMPOSED_SELECTOR}${SHADOW_ROOT_COUNT}
     if (composedClosest(el, '[inert]')) continue;
     els.push(el);
   }
-  window.__kbProbe = { els: els, path: composedSelectorPath };
+  window.__kbProbe = { els: els, path: composedSelectorPath,
+    scope: modal ? composedSelectorPath(modal) : null };
   const TEXTLIKE = ['button', 'submit', 'reset', 'checkbox', 'radio', 'range',
                     'color', 'file', 'image'];
   return els.map((el, i) => {
@@ -176,6 +179,7 @@ export const FRAME_COUNT = `() => {
 ${QUERY_ALL}${IFRAME_COUNT}
   return countFrames(document.body);
 }`;
+export const SCOPE = `() => (window.__kbProbe && window.__kbProbe.scope) || null`;
 export const ACTIVE = `() => {
 ${DEEP_ACTIVE_ELEMENT}
   const p = window.__kbProbe || { els: [] };

package/package.json

@@ -1,12 +1,11 @@
 {
   "name": "@okent/accessibility-scanner-keyboard-plugin",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Keyboard probe plugin for github/accessibility-scanner: focus traps, unreachable controls, removed focus indicators, and focus-order divergence, found by walking the real Tab order.",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/owenpkent/accessibility-tooling.git",
-    "directory": "plugins/keyboard-scan"
+    "url": "git+https://github.com/owenpkent/accessibility-scanner-keyboard-plugin.git"
   },
   "type": "module",
   "main": "./dist/index.js",
@@ -56,5 +55,9 @@
     "playwright": "^1.50.0",
     "typescript": "^5.5.0",
     "vitest": "^3.0.0"
+  },
+  "homepage": "https://github.com/owenpkent/accessibility-scanner-keyboard-plugin#readme",
+  "bugs": {
+    "url": "https://github.com/owenpkent/accessibility-scanner-keyboard-plugin/issues"
   }
 }