accented 0.0.0-20250404114312 → 0.0.0-20250424114613

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/update-elements-with-issues.test.ts

@@ -18,7 +18,8 @@ const win: Window & { CSS: typeof CSS } = {
         setProperty: () => {}
       },
       dataset: {}
-    })
+    }),
+    contains: () => true,
   },
   // @ts-expect-error we're missing a lot of properties
   getComputedStyle: () => ({
@@ -41,7 +42,8 @@ const baseElement = {
   getRootNode,
   style: {
     getPropertyValue: () => ''
-  }
+  },
+  closest: () => null,
 }
 
 // @ts-expect-error element is not HTMLElement
@@ -144,6 +146,11 @@ const issue3: Issue = {
   ...commonIssueProps
 };
 
+const scanContext = {
+  include: [win.document],
+  exclude: []
+}
+
 suite('updateElementsWithIssues', () => {
   test('no changes', () => {
     const extendedElementsWithIssues: Signal<Array<ExtendedElementWithIssues>> = signal([
@@ -151,6 +158,7 @@ suite('updateElementsWithIssues', () => {
         id: 1,
         element: element1,
         rootNode,
+        skipRender: false,
         position,
         visible,
         trigger,
@@ -162,6 +170,7 @@ suite('updateElementsWithIssues', () => {
         id: 2,
         element: element2,
         rootNode,
+        skipRender: false,
         position,
         visible,
         trigger,
@@ -170,7 +179,13 @@ suite('updateElementsWithIssues', () => {
         issues: signal([issue2])
       }
     ]);
-    updateElementsWithIssues(extendedElementsWithIssues, [violation1, violation2], win, 'accented');
+    updateElementsWithIssues({
+      extendedElementsWithIssues,
+      scanContext,
+      violations: [violation1, violation2],
+      win,
+      name: 'accented'
+    });
     assert.equal(extendedElementsWithIssues.value.length, 2);
     assert.equal(extendedElementsWithIssues.value[0]?.element, element1);
     assert.equal(extendedElementsWithIssues.value[0]?.issues.value.length, 1);
@@ -184,6 +199,7 @@ suite('updateElementsWithIssues', () => {
         id: 1,
         element: element1,
         rootNode,
+        skipRender: false,
         position,
         visible,
         trigger,
@@ -195,6 +211,7 @@ suite('updateElementsWithIssues', () => {
         id: 2,
         element: element2,
         rootNode,
+        skipRender: false,
         position,
         visible,
         trigger,
@@ -203,7 +220,13 @@ suite('updateElementsWithIssues', () => {
         issues: signal([issue2])
       }
     ]);
-    updateElementsWithIssues(extendedElementsWithIssues, [violation1, violation2, violation3], win, 'accented');
+    updateElementsWithIssues({
+      extendedElementsWithIssues,
+      scanContext,
+      violations: [violation1, violation2, violation3],
+      win,
+      name: 'accented'
+    });
     assert.equal(extendedElementsWithIssues.value.length, 2);
     assert.equal(extendedElementsWithIssues.value[0]?.element, element1);
     assert.equal(extendedElementsWithIssues.value[0]?.issues.value.length, 1);
@@ -217,6 +240,7 @@ suite('updateElementsWithIssues', () => {
         id: 1,
         element: element1,
         rootNode,
+        skipRender: false,
         position,
         visible,
         trigger,
@@ -228,6 +252,7 @@ suite('updateElementsWithIssues', () => {
         id: 2,
         element: element2,
         rootNode,
+        skipRender: false,
         position,
         visible,
         trigger,
@@ -236,7 +261,13 @@ suite('updateElementsWithIssues', () => {
         issues: signal([issue2, issue3])
       }
     ]);
-    updateElementsWithIssues(extendedElementsWithIssues, [violation1, violation2], win, 'accented');
+    updateElementsWithIssues({
+      extendedElementsWithIssues,
+      scanContext,
+      violations: [violation1, violation2],
+      win,
+      name: 'accented'
+    });
     assert.equal(extendedElementsWithIssues.value.length, 2);
     assert.equal(extendedElementsWithIssues.value[0]?.element, element1);
     assert.equal(extendedElementsWithIssues.value[0]?.issues.value.length, 1);
@@ -250,6 +281,7 @@ suite('updateElementsWithIssues', () => {
         id: 1,
         element: element1,
         rootNode,
+        skipRender: false,
         position,
         visible,
         trigger,
@@ -258,7 +290,13 @@ suite('updateElementsWithIssues', () => {
         issues: signal([issue1])
       }
     ]);
-    updateElementsWithIssues(extendedElementsWithIssues, [violation1, violation2], win, 'accented');
+    updateElementsWithIssues({
+      extendedElementsWithIssues,
+      scanContext,
+      violations: [violation1, violation2],
+      win,
+      name: 'accented'
+    });
     assert.equal(extendedElementsWithIssues.value.length, 2);
     assert.equal(extendedElementsWithIssues.value[0]?.element, element1);
     assert.equal(extendedElementsWithIssues.value[0]?.issues.value.length, 1);
@@ -272,6 +310,7 @@ suite('updateElementsWithIssues', () => {
         id: 1,
         element: element1,
         rootNode,
+        skipRender: false,
         position,
         visible,
         trigger,
@@ -280,7 +319,13 @@ suite('updateElementsWithIssues', () => {
         issues: signal([issue1])
       }
     ]);
-    updateElementsWithIssues(extendedElementsWithIssues, [violation1, violation4], win, 'accented');
+    updateElementsWithIssues({
+      extendedElementsWithIssues,
+      scanContext,
+      violations: [violation1, violation4],
+      win,
+      name: 'accented'
+    });
     assert.equal(extendedElementsWithIssues.value.length, 1);
     assert.equal(extendedElementsWithIssues.value[0]?.element, element1);
   });
@@ -291,6 +336,7 @@ suite('updateElementsWithIssues', () => {
         id: 1,
         element: element1,
         rootNode,
+        skipRender: false,
         position,
         visible,
         trigger,
@@ -302,6 +348,7 @@ suite('updateElementsWithIssues', () => {
         id: 2,
         element: element2,
         rootNode,
+        skipRender: false,
         position,
         visible,
         trigger,
@@ -310,7 +357,13 @@ suite('updateElementsWithIssues', () => {
         issues: signal([issue2])
       }
     ]);
-    updateElementsWithIssues(extendedElementsWithIssues, [violation1], win, 'accented');
+    updateElementsWithIssues({
+      extendedElementsWithIssues,
+      scanContext,
+      violations: [violation1],
+      win,
+      name: 'accented'
+    });
     assert.equal(extendedElementsWithIssues.value.length, 1);
     assert.equal(extendedElementsWithIssues.value[0]?.element, element1);
     assert.equal(extendedElementsWithIssues.value[0]?.issues.value.length, 1);

package/src/utils/update-elements-with-issues.ts

@@ -1,19 +1,51 @@
 import type { AxeResults } from 'axe-core';
 import type { Signal } from '@preact/signals-core';
 import { batch, signal } from '@preact/signals-core';
-import type { ExtendedElementWithIssues } from '../types';
+import type { ExtendedElementWithIssues, ScanContext } from '../types';
 import transformViolations from './transform-violations.js';
 import areElementsWithIssuesEqual from './are-elements-with-issues-equal.js';
 import areIssueSetsEqual from './are-issue-sets-equal.js';
+import isNodeInScanContext from './is-node-in-scan-context.js';
 import type { AccentedTrigger } from '../elements/accented-trigger';
 import type { AccentedDialog } from '../elements/accented-dialog';
 import getElementPosition from './get-element-position.js';
 import getScrollableAncestors from './get-scrollable-ancestors.js';
 import supportsAnchorPositioning from './supports-anchor-positioning.js';
+import { isSvgElement } from './dom-helpers.js';
+import getParent from './get-parent.js';
+
+function shouldSkipRender(element: Element): boolean {
+
+  // Skip rendering if the element is inside an SVG:
+  // https://github.com/pomerantsev/accented/issues/62
+  const parent = getParent(element);
+  const isInsideSvg = Boolean(parent && isSvgElement(parent));
+
+  // Some issues, such as meta-viewport, are on <head> descendants,
+  // but since <head> is never rendered, we don't want to output anything
+  // for those in the DOM.
+  // We're not anticipating the use of shadow DOM in <head>,
+  // so the use of .closest() should be fine.
+  const isInsideHead = element.closest('head') !== null;
+
+  return isInsideSvg || isInsideHead;
+}
 
 let count = 0;
 
-export default function updateElementsWithIssues(extendedElementsWithIssues: Signal<Array<ExtendedElementWithIssues>>, violations: typeof AxeResults.violations, win: Window & { CSS: typeof CSS }, name: string) {
+export default function updateElementsWithIssues({
+  extendedElementsWithIssues,
+  scanContext,
+  violations,
+  win,
+  name
+}: {
+  extendedElementsWithIssues: Signal<Array<ExtendedElementWithIssues>>,
+  scanContext: ScanContext,
+  violations: typeof AxeResults.violations,
+  win: Window & { CSS: typeof CSS },
+  name: string
+}) {
   const updatedElementsWithIssues = transformViolations(violations, name);
 
   batch(() => {
@@ -28,8 +60,14 @@ export default function updateElementsWithIssues(extendedElementsWithIssues: Sig
       return !extendedElementsWithIssues.value.some(extendedElementWithIssues => areElementsWithIssuesEqual(extendedElementWithIssues, updatedElementWithIssues));
     });
 
+    // Only consider an element to be removed in two cases:
+    // 1. It has been removed from the DOM.
+    // 2. It is within the scan context, but not among updatedElementsWithIssues.
     const removedElementsWithIssues = extendedElementsWithIssues.value.filter(extendedElementWithIssues => {
-      return !updatedElementsWithIssues.some(updatedElementWithIssues => areElementsWithIssuesEqual(updatedElementWithIssues, extendedElementWithIssues));
+      const isConnected = extendedElementWithIssues.element.isConnected;
+      const hasNoMoreIssues = isNodeInScanContext(extendedElementWithIssues.element, scanContext)
+        && !updatedElementsWithIssues.some(updatedElementWithIssues => areElementsWithIssuesEqual(updatedElementWithIssues, extendedElementWithIssues));
+      return !isConnected || hasNoMoreIssues;
     });
 
     if (addedElementsWithIssues.length > 0 || removedElementsWithIssues.length > 0) {
@@ -63,6 +101,7 @@ export default function updateElementsWithIssues(extendedElementsWithIssues: Sig
             return {
               id,
               element: addedElementWithIssues.element,
+              skipRender: shouldSkipRender(addedElementWithIssues.element),
               rootNode: addedElementWithIssues.rootNode,
               visible: trigger.visible,
               position: trigger.position,

package/src/validate-options.ts

@@ -1,5 +1,89 @@
-import type { AccentedOptions } from './types';
+import type { Selector, SelectorList, ContextProp, ContextObject, AccentedOptions, Context } from './types';
 import { allowedAxeOptions } from './types.js';
+import { isNode, isNodeList } from './utils/dom-helpers.js';
+
+function isSelector(contextFragment: Context): contextFragment is Selector {
+  return typeof contextFragment === 'string'
+    || isNode(contextFragment)
+    || 'fromShadowDom' in contextFragment;
+}
+
+function validateSelector(selector: Selector) {
+  if (typeof selector === 'string') {
+    return;
+  } else if (isNode(selector)) {
+    return;
+  } else if ('fromShadowDom' in selector) {
+    if (!Array.isArray(selector.fromShadowDom)
+      || selector.fromShadowDom.length < 2 ||
+      !selector.fromShadowDom.every(item => typeof item === 'string')
+    ) {
+      throw new TypeError(`Accented: invalid argument. \`fromShadowDom\` must be an array of strings with at least 2 elements. It’s currently set to ${selector.fromShadowDom}.`);
+    }
+    return;
+  } else {
+    const neverSelector: never = selector;
+    throw new TypeError(`Accented: invalid argument. The selector must be one of: string, Node, or an object with a \`fromShadowDom\` property. It’s currently set to ${neverSelector}.`);
+  }
+}
+
+function isSelectorList(contextFragment: Context): contextFragment is SelectorList {
+  return (typeof contextFragment === 'object' && isNodeList(contextFragment))
+    || (Array.isArray(contextFragment) && contextFragment.every(item => isSelector(item)));
+}
+
+function validateSelectorList(selectorList: SelectorList) {
+  if (isNodeList(selectorList)) {
+    return;
+  } else if (Array.isArray(selectorList)) {
+    for (const selector of selectorList) {
+      validateSelector(selector);
+    }
+  } else {
+    const neverSelectorList: never = selectorList;
+    throw new TypeError(`Accented: invalid argument. The selector list must either be a NodeList or an array. It’s currently set to ${neverSelectorList}.`);
+  }
+}
+
+function isContextProp(contextFragment: Context): contextFragment is ContextProp {
+  return isSelector(contextFragment) || isSelectorList(contextFragment);
+}
+
+function validateContextProp(context: Selector | SelectorList) {
+  if (isSelector(context)) {
+    validateSelector(context);
+  } else if (isSelectorList(context)) {
+    validateSelectorList(context);
+  } else {
+    const neverContext: never = context;
+    throw new TypeError(`Accented: invalid argument. The context property must either be a selector or a selector list. It’s currently set to ${neverContext}.`);
+  }
+}
+
+function isContextObject(contextFragment: Context): contextFragment is ContextObject {
+  return typeof contextFragment === 'object' && contextFragment !== null
+    && ('include' in contextFragment || 'exclude' in contextFragment);
+}
+
+function validateContextObject(contextObject: ContextObject) {
+  if ('include' in contextObject) {
+    validateContextProp(contextObject.include!);
+  }
+  if ('exclude' in contextObject) {
+    validateContextProp(contextObject.exclude!);
+  }
+}
+
+function validateContext(context: Context) {
+  if (isContextProp(context)) {
+    validateContextProp(context);
+  } else if (isContextObject(context)) {
+    validateContextObject(context);
+  } else {
+    const neverContext: never = context;
+    throw new TypeError(`Accented: invalid context argument. It’s currently set to ${neverContext}.`);
+  }
+}
 
 // The space of valid CSS and HTML names is wider than this,
 // but with Unicode it gets complicated quickly, so I'm sticking to only allowing
@@ -41,4 +125,7 @@ export default function validateOptions(options: AccentedOptions) {
       throw new TypeError(`Accented: invalid argument. \`axeOptions\` contains the following unsupported keys: ${unsupportedKeys.join(', ')}. Valid options are: ${allowedAxeOptions.join(', ')}.`);
     }
   }
+  if (options.context !== undefined) {
+    validateContext(options.context);
+  }
 }