accented 0.0.0-20250303013509 → 0.0.0-20250424114613

package/src/utils/get-scan-context.test.ts

@@ -0,0 +1,79 @@
+import { JSDOM } from 'jsdom';
+import assert from 'node:assert/strict';
+import { suite, test } from 'node:test';
+import getScanContext from './get-scan-context';
+
+suite('getScanContext', () => {
+  test('when context doesn’t overlap with nodes, the result is empty', () => {
+    const dom = new JSDOM('<div><div id="context"></div><div id="mutated-node"></div></div>');
+    const { document } = dom.window;
+    global.document = document;
+    const mutatedNode = document.querySelector('#mutated-node')!;
+    const scanContext = getScanContext([mutatedNode], '#context');
+
+    assert.deepEqual(scanContext, {
+      include: [],
+      exclude: []
+    });
+  });
+
+  test('when context is within the mutated node, the result is the context', () => {
+    const dom = new JSDOM('<div><div id="mutated-node"><div id="context"></div></div></div>');
+    const { document } = dom.window;
+    global.document = document;
+    const mutatedNode = document.querySelector('#mutated-node')!;
+    const scanContext = getScanContext([mutatedNode], '#context');
+    const contextNode = document.querySelector('#context')!;
+
+    assert.deepEqual(scanContext, {
+      include: [contextNode],
+      exclude: []
+    });
+  });
+
+  test('when mutated node is within context, the mutated node and the context nodes within it are correctly included / excluded', () => {
+    const dom = new JSDOM(`<div>
+      <div class="include" id="outer-include">
+        <div id="mutated-node">
+          <div class="exclude" id="inner-exclude">
+            <div class="include" id="inner-include"></div>
+          </div>
+        </div>
+      </div>
+    </div>`);
+    const { document } = dom.window;
+    global.document = document;
+    const mutatedNode = document.querySelector('#mutated-node')!;
+    const scanContext = getScanContext([mutatedNode], {include: ['.include'], exclude: ['.exclude']});
+    const innerExclude = document.querySelector('#inner-exclude')!;
+    const innerInclude = document.querySelector('#inner-include')!;
+
+    assert.deepEqual(scanContext, {
+      include: [mutatedNode, innerInclude],
+      exclude: [innerExclude]
+    });
+  });
+
+  test('when mutated node is within exclude, context elements within it are still included', () => {
+    const dom = new JSDOM(`<div>
+      <div class="exclude" id="outer-exclude">
+        <div id="mutated-node">
+          <div class="exclude" id="inner-exclude">
+            <div class="include" id="inner-include"></div>
+          </div>
+        </div>
+      </div>
+    </div>`);
+    const { document } = dom.window;
+    global.document = document;
+    const mutatedNode = document.querySelector('#mutated-node')!;
+    const scanContext = getScanContext([mutatedNode], {include: ['.include'], exclude: ['.exclude']});
+    const innerExclude = document.querySelector('#inner-exclude')!;
+    const innerInclude = document.querySelector('#inner-include')!;
+
+    assert.deepEqual(scanContext, {
+      include: [innerInclude],
+      exclude: [innerExclude]
+    });
+  });
+});

package/src/utils/get-scan-context.ts

@@ -0,0 +1,39 @@
+import type { Context, ScanContext } from '../types';
+import contains from './contains.js';
+import { deduplicateNodes } from './deduplicate-nodes.js';
+import isNodeInScanContext from './is-node-in-scan-context.js';
+import normalizeContext from './normalize-context.js';
+
+export default function getScanContext(nodes: Array<Node>, context: Context): ScanContext {
+  const {
+    include: contextInclude,
+    exclude: contextExclude
+  } = normalizeContext(context);
+
+  // Filter only nodes that are included by context (see isNodeInContext above).
+  const nodesInContext = nodes.filter(node =>
+    isNodeInScanContext(node, {
+      include: contextInclude,
+      exclude: contextExclude
+    })
+  );
+
+  const include: Array<Node> = [];
+  const exclude: Array<Node> = [];
+
+  // Adds all nodesInContext to the include array.
+  include.push(...nodesInContext);
+
+  // Now add any included and excluded context nodes that are contained by any of the original nodes.
+  for (const node of nodes) {
+    const includeDescendants = contextInclude.filter(item => contains(node, item));
+    include.push(...includeDescendants);
+    const excludeDescendants = contextExclude.filter(item => contains(node, item));
+    exclude.push(...excludeDescendants);
+  }
+
+  return {
+    include: deduplicateNodes(include),
+    exclude: deduplicateNodes(exclude)
+  };
+}

package/src/utils/get-scrollable-ancestors.ts

@@ -1,10 +1,15 @@
+import getParent from './get-parent.js';
+
 const scrollableOverflowValues = new Set(['auto', 'scroll', 'hidden']);
 
-export default function getScrollableAncestors (element: HTMLElement, win: Window) {
-  let currentElement = element;
-  let scrollableAncestors = new Set<HTMLElement>();
-  while (currentElement.parentElement) {
-    currentElement = currentElement.parentElement;
+export default function getScrollableAncestors (element: Element, win: Window) {
+  let currentElement: Element | null = element;
+  let scrollableAncestors = new Set<Element>();
+  while (true) {
+    currentElement = getParent(currentElement);
+    if (!currentElement) {
+      break;
+    }
     const computedStyle = win.getComputedStyle(currentElement);
     if (scrollableOverflowValues.has(computedStyle.overflowX) || scrollableOverflowValues.has(computedStyle.overflowY)) {
       scrollableAncestors.add(currentElement);

package/src/utils/is-node-in-scan-context.test.ts

@@ -0,0 +1,70 @@
+import { JSDOM } from 'jsdom';
+import assert from 'node:assert/strict';
+import {suite, test} from 'node:test';
+import isNodeInScanContext from './is-node-in-scan-context';
+
+suite('isNodeInScanContext', () => {
+  test('doesn’t include an element if scan context is empty', () => {
+    const dom = new JSDOM('<div id="test"></div>');
+    const { document } = dom.window;
+    const node = document.querySelector('#test')!;
+
+    const scanContext = { include: [], exclude: [] };
+
+    assert.equal(isNodeInScanContext(node, scanContext), false);
+  });
+
+  test('includes an element whose ancestor is included', () => {
+    const dom = new JSDOM('<div id="test"></div>');
+    const { document } = dom.window;
+    const node = document.querySelector('#test')!;
+    const body = document.body;
+
+    const scanContext = { include: [body], exclude: [] };
+
+    assert.ok(isNodeInScanContext(node, scanContext));
+  });
+
+  test('does not include an element whose closest ancestor is excluded', () => {
+    const dom = new JSDOM('<div id="excluded"><div id="test"></div></div>');
+    const { document } = dom.window;
+    const node = document.querySelector('#test')!;
+    const body = document.body;
+    const excludedAncestor = document.querySelector('#excluded')!;
+
+    const scanContext = { include: [body], exclude: [excludedAncestor] };
+
+    assert.equal(isNodeInScanContext(node, scanContext), false);
+  });
+
+  test('includes an element if it itself is included', () => {
+    const dom = new JSDOM('<div id="test"></div>');
+    const { document } = dom.window;
+    const node = document.querySelector('#test')!;
+
+    const scanContext = { include: [node], exclude: [] };
+
+    assert.ok(isNodeInScanContext(node, scanContext));
+  });
+
+  test('doesn’t include an element if it itself is excluded', () => {
+    const dom = new JSDOM('<div id="test"></div>');
+    const { document } = dom.window;
+    const node = document.querySelector('#test')!;
+    const body = document.body;
+
+    const scanContext = { include: [body], exclude: [node] };
+
+    assert.equal(isNodeInScanContext(node, scanContext), false);
+  });
+
+  test('includes an element if it’s both included and excluded (include takes precedence)', () => {
+    const dom = new JSDOM('<div id="test"></div>');
+    const { document } = dom.window;
+    const node = document.querySelector('#test')!;
+
+    const scanContext = { include: [node], exclude: [node] };
+
+    assert.ok(isNodeInScanContext(node, scanContext));
+  });
+});

package/src/utils/is-node-in-scan-context.ts

@@ -0,0 +1,29 @@
+/* Adapted from https://github.com/dequelabs/axe-core/blob/fd6239bfc97ebc904044f93f68d7e49137f744ad/lib/core/utils/is-node-in-context.js */
+
+import type { ScanContext } from '../types';
+import contains from './contains.js';
+import ensureNonEmpty from './ensure-non-empty.js';
+
+function getDeepest(nodes: [Node, ...Node[]]): Node {
+  let deepest = nodes[0];
+  for (const node of nodes.slice(1)) {
+    if (!contains(node, deepest)) {
+      deepest = node;
+    }
+  }
+  return deepest;
+}
+
+export default function isNodeInScanContext(node: Node, { include, exclude }: ScanContext): boolean {
+  const filteredInclude = include.filter(includeNode => contains(includeNode, node));
+  if (filteredInclude.length === 0) {
+    return false;
+  }
+  const filteredExclude = exclude.filter(excludeNode => contains(excludeNode, node));
+  if (filteredExclude.length === 0) {
+    return true;
+  }
+  const deepestInclude = getDeepest(ensureNonEmpty(filteredInclude));
+  const deepestExclude = getDeepest(ensureNonEmpty(filteredExclude));
+  return contains(deepestExclude, deepestInclude);
+}

package/src/utils/normalize-context.test.ts

@@ -0,0 +1,105 @@
+import { JSDOM } from 'jsdom';
+import assert from 'node:assert/strict';
+import { suite, test } from 'node:test';
+import normalizeContext from './normalize-context';
+
+suite('normalizeContext', () => {
+  test('when document is passed, only document is returned in include', () => {
+    const dom = new JSDOM('<div id="test"></div>');
+    const { document } = dom.window;
+    const normalizedContext = normalizeContext(document);
+
+    assert.deepEqual(normalizedContext, {
+      include: [document],
+      exclude: []
+    });
+  });
+
+  test('when an element is passed, only that element is returned in include', () => {
+    const dom = new JSDOM('<div id="test"></div>');
+    const { document } = dom.window;
+    const element = document.querySelector('#test')!;
+    const normalizedContext = normalizeContext(element);
+
+    assert.deepEqual(normalizedContext, {
+      include: [element],
+      exclude: []
+    });
+  });
+
+  test('when a selector is passed and elements matching that selector exist, all those elements are included', () => {
+    const dom = new JSDOM(`<div>
+      <div class="matches"></div>
+      <div class="matches"></div>
+      <div class="doesnt-match"></div>
+    </div>`);
+    const { document } = dom.window;
+    global.document = document;
+    const matchingElements = Array.from(document.querySelectorAll('.matches'));
+    const normalizedContext = normalizeContext('.matches');
+
+    assert.equal(matchingElements.length, 2);
+    assert.deepEqual(normalizedContext, {
+      include: matchingElements,
+      exclude: []
+    });
+  });
+
+  test('when a selector is passed and no elements matching that selector exist, `include` is empty', () => {
+    const dom = new JSDOM(`<div>
+      <div class="doesnt-match"></div>
+      <div class="doesnt-match"></div>
+      <div class="doesnt-match"></div>
+    </div>`);
+    const { document } = dom.window;
+    global.document = document;
+    const normalizedContext = normalizeContext('.matches');
+
+    assert.deepEqual(normalizedContext, {
+      include: [],
+      exclude: []
+    });
+  });
+
+  test('when a node list is passed, all the nodes from the list are included', () => {
+    const dom = new JSDOM(`<div>
+      <div class="matches"></div>
+      <div class="matches"></div>
+      <div class="doesnt-match"></div>
+    </div>`);
+    const { document } = dom.window;
+    const matchingElements = document.querySelectorAll('.matches');
+    const normalizedContext = normalizeContext(matchingElements);
+
+    assert.equal(matchingElements.length, 2);
+    assert.deepEqual(normalizedContext, {
+      include: Array.from(matchingElements),
+      exclude: []
+    });
+  });
+
+  test('when an object with `fromShadowDom` is passed, all the matching nodes are included', () => {
+    const dom = new JSDOM(`<div>
+      <div class="host"></div>
+      <div class="host"></div>
+    </div>`);
+    const { document } = dom.window;
+    global.document = document;
+    const hosts = document.querySelectorAll('.host');
+    const matchingElements = [];
+    for (const host of hosts) {
+      const shadowRoot = host.attachShadow({ mode: 'open' });
+      const matchingElement = document.createElement('div');
+      matchingElement.classList.add('matches');
+      shadowRoot.appendChild(matchingElement);
+      matchingElements.push(matchingElement);
+    }
+    const normalizedContext = normalizeContext({fromShadowDom: ['.host', '.matches']});
+
+    assert.equal(matchingElements.length, 2);
+    assert.deepEqual(normalizedContext, {
+      include: matchingElements,
+      exclude: []
+    });
+  });
+});

package/src/utils/normalize-context.ts

@@ -0,0 +1,58 @@
+import type { Context, ContextProp, Selector, ScanContext } from '../types';
+import { isNode, isNodeList } from './dom-helpers.js';
+import { deduplicateNodes } from './deduplicate-nodes.js';
+
+function recursiveSelectAll(selectors: Array<string>, root: Document | ShadowRoot): Array<Node> {
+  const nodesOnCurrentLevel = root.querySelectorAll(selectors[0]!);
+  if (selectors.length === 1) {
+    return Array.from(nodesOnCurrentLevel);
+  }
+  const restSelectors: Array<string> = selectors.slice(1);
+  const selected = [];
+  for (const node of nodesOnCurrentLevel) {
+    if (node.shadowRoot) {
+      selected.push(...recursiveSelectAll(restSelectors, node.shadowRoot));
+    }
+  }
+  return selected;
+}
+
+function selectorToNodes(selector: Selector): Array<Node> {
+  if (typeof selector === 'string') {
+    return recursiveSelectAll([selector], document);
+  } else if (isNode(selector)) {
+    return [selector];
+  } else {
+    return recursiveSelectAll(selector.fromShadowDom, document);
+  }
+}
+
+function contextPropToNodes(contextProp: ContextProp): Array<Node> {
+  let nodes: Array<Node> = [];
+  if (typeof contextProp === 'object' && (Array.isArray(contextProp) || isNodeList(contextProp))) {
+    nodes = Array.from(contextProp).map(item => selectorToNodes(item)).flat();
+  } else {
+    nodes = selectorToNodes(contextProp);
+  }
+  return deduplicateNodes(nodes);
+}
+
+export default function normalizeContext(context: Context): ScanContext {
+  let contextInclude: Array<Node> = [];
+  let contextExclude: Array<Node> = [];
+  if (typeof context === 'object' && ('include' in context || 'exclude' in context)) {
+    if (context.include !== undefined) {
+      contextInclude = contextPropToNodes(context.include);
+    }
+    if (context.exclude !== undefined) {
+      contextExclude = contextPropToNodes(context.exclude);
+    }
+  } else {
+    contextInclude = contextPropToNodes(context);
+  }
+
+  return {
+    include: contextInclude,
+    exclude: contextExclude
+  };
+}

package/src/utils/shadow-dom-aware-mutation-observer.ts

@@ -0,0 +1,78 @@
+import { isElement, isDocument, isDocumentFragment } from './dom-helpers.js';
+import { getAccentedElementNames } from '../constants.js';
+
+export default function createShadowDOMAwareMutationObserver (name: string, callback: MutationCallback) {
+  class ShadowDOMAwareMutationObserver extends MutationObserver {
+    #shadowRoots = new Set();
+
+    #options: MutationObserverInit | undefined;
+
+    constructor(callback: MutationCallback) {
+      super((mutations, observer) => {
+        const accentedElementNames = getAccentedElementNames(name);
+        const childListMutations = mutations
+          .filter(mutation => mutation.type === 'childList')
+
+        const newElements = childListMutations
+          .map(mutation => [...mutation.addedNodes])
+          .flat()
+          .filter(node => isElement(node))
+          .filter(node => !accentedElementNames.includes(node.nodeName.toLowerCase()));
+
+        this.#observeShadowRoots(newElements);
+
+        const removedElements = childListMutations
+          .map(mutation => [...mutation.removedNodes])
+          .flat()
+          .filter(node => isElement(node))
+          .filter(node => !accentedElementNames.includes(node.nodeName.toLowerCase()));
+
+        // Mutation observer has no "unobserve" method, so we're simply deleting
+        // the elements from the set of shadow roots.
+        this.#deleteShadowRoots(removedElements);
+
+        callback(mutations, observer);
+      });
+    }
+
+    override observe(target: Node, options?: MutationObserverInit): void {
+      this.#options ??= options;
+      if (isElement(target) || isDocument(target) || isDocumentFragment(target)) {
+        this.#observeShadowRoots([target]);
+      }
+      super.observe(target, options);
+    }
+
+    override disconnect(): void {
+      this.#shadowRoots.clear();
+      super.disconnect();
+    }
+
+    #observeShadowRoots = (elements: Array<Element | Document | DocumentFragment>) => {
+      const shadowRoots = elements
+        .map(element => [...element.querySelectorAll('*')])
+        .flat()
+        .filter(element => element.shadowRoot)
+        .map(element => element.shadowRoot!);
+
+      for (const shadowRoot of shadowRoots) {
+        this.#shadowRoots.add(shadowRoot);
+        this.observe(shadowRoot, this.#options);
+      }
+    }
+
+    #deleteShadowRoots = (elements: Array<Element | Document | DocumentFragment>) => {
+      const shadowRoots = elements
+        .map(element => [...element.querySelectorAll('*')])
+        .flat()
+        .filter(element => element.shadowRoot)
+        .map(element => element.shadowRoot!);
+
+      for (const shadowRoot of shadowRoots) {
+        this.#shadowRoots.delete(shadowRoot);
+      }
+    }
+  }
+
+  return new ShadowDOMAwareMutationObserver(callback);
+}

package/src/utils/transform-violations.test.ts

@@ -24,12 +24,14 @@ const commonViolationProps2: Omit<Violation, 'nodes'> = {
   impact: 'serious'
 };
 
+const getRootNode = (): Node => ({} as Node);
+
 // @ts-expect-error element is not HTMLElement
-const element1: HTMLElement = {};
+const element1: HTMLElement = {getRootNode};
 // @ts-expect-error element is not HTMLElement
-const element2: HTMLElement = {};
+const element2: HTMLElement = {getRootNode};
 // @ts-expect-error element is not HTMLElement
-const element3: HTMLElement = {};
+const element3: HTMLElement = {getRootNode};
 
 const commonNodeProps = {
   html: '<div></div>',
@@ -65,7 +67,7 @@ suite('transformViolations', () => {
       ...commonViolationProps1,
       nodes: [node1]
     };
-    const elementsWithIssues = transformViolations([violation]);
+    const elementsWithIssues = transformViolations([violation], 'accented');
     assert.equal(elementsWithIssues.length, 1);
     assert.equal(elementsWithIssues[0]?.element, element1);
     assert.equal(elementsWithIssues[0].issues.length, 1);
@@ -82,7 +84,7 @@ suite('transformViolations', () => {
       ...commonViolationProps2,
       nodes: [node1, node3]
     };
-    const elementsWithIssues = transformViolations([violation1, violation2]);
+    const elementsWithIssues = transformViolations([violation1, violation2], 'accented');
     assert.equal(elementsWithIssues.length, 3);
     const elementWithTwoIssues = elementsWithIssues.find(elementWithIssues => elementWithIssues.element === element1);
     assert.equal(elementWithTwoIssues?.issues.length, 2);
@@ -101,7 +103,7 @@ suite('transformViolations', () => {
       nodes: [node]
     };
 
-    const elementsWithIssues = transformViolations([violation]);
+    const elementsWithIssues = transformViolations([violation], 'accented');
     assert.equal(elementsWithIssues.length, 0);
   });
 
@@ -118,7 +120,7 @@ suite('transformViolations', () => {
       nodes: [node]
     };
 
-    const elementsWithIssues = transformViolations([violation]);
-    assert.equal(elementsWithIssues.length, 0);
+    const elementsWithIssues = transformViolations([violation], 'accented');
+    assert.equal(elementsWithIssues.length, 1);
   });
 });

package/src/utils/transform-violations.ts

@@ -1,12 +1,29 @@
 import type { AxeResults, ImpactValue } from 'axe-core';
 import type { Issue, ElementWithIssues } from '../types';
 
+// This is a list of axe-core violations (their ids) that may be flagged by axe-core
+// as false positives if an Accented trigger is a descendant of the element with the issue.
+const violationsAffectedByAccentedTriggers = [
+  'aria-hidden-focus',
+  'aria-text',
+  'definition-list',
+  'label-content-name-mismatch',
+  'list',
+  'nested-interactive',
+  'scrollable-region-focusable' // The Accented trigger might make the content grow such that scrolling is required.
+];
+
+function maybeCausedByAccented(violationId: string, element: HTMLElement, name: string) {
+  return violationsAffectedByAccentedTriggers.includes(violationId)
+    && Boolean(element.querySelector(`${name}-trigger`));
+}
+
 function impactCompare(a: ImpactValue, b: ImpactValue) {
   const impactOrder = [null, 'minor', 'moderate', 'serious', 'critical'];
   return impactOrder.indexOf(a) - impactOrder.indexOf(b);
 }
 
-export default function transformViolations(violations: typeof AxeResults.violations) {
+export default function transformViolations(violations: typeof AxeResults.violations, name: string) {
   const elementsWithIssues: Array<ElementWithIssues> = [];
 
   for (const violation of violations) {
@@ -21,11 +38,7 @@ export default function transformViolations(violations: typeof AxeResults.violat
       // A consumer of Accented can instead scan the iframed document by calling Accented initialization from that document.
       const isInIframe = target.length > 1;
 
-      // Highlighting elements in shadow DOM is not yet supported, see https://github.com/pomerantsev/accented/issues/25
-      // Until then, we don’t want such elements to be added to the set.
-      const isInShadowDOM = Array.isArray(target[0]);
-
-      if (element && !isInIframe && !isInShadowDOM) {
+      if (element && !isInIframe && !maybeCausedByAccented(violation.id, element, name)) {
         const issue: Issue = {
           id: violation.id,
           title: violation.help,
@@ -37,6 +50,7 @@ export default function transformViolations(violations: typeof AxeResults.violat
         if (existingElementIndex === -1) {
           elementsWithIssues.push({
             element,
+            rootNode: element.getRootNode(),
             issues: [issue]
           });
         } else {