accented 0.0.2 → 1.0.1

package/src/scanner.ts

@@ -1,18 +1,26 @@
 import axe from 'axe-core';
-import TaskQueue from './task-queue.js';
+import { getAccentedElementNames, issuesUrl } from './constants.js';
+import { logAndRethrow } from './log-and-rethrow.js';
 import { elementsWithIssues, enabled, extendedElementsWithIssues } from './state.js';
-import type { AxeOptions, Throttle, Callback, AxeContext } from './types';
-import updateElementsWithIssues from './utils/update-elements-with-issues.js';
-import recalculatePositions from './utils/recalculate-positions.js';
-import recalculateScrollableAncestors from './utils/recalculate-scrollable-ancestors.js';
-import supportsAnchorPositioning from './utils/supports-anchor-positioning.js';
-import { issuesUrl } from './constants.js';
-import logAndRethrow from './log-and-rethrow.js';
-
-export default function createScanner(name: string, axeContext: AxeContext, axeOptions: AxeOptions, throttle: Required<Throttle>, callback: Callback) {
+import { TaskQueue } from './task-queue.js';
+import type { AxeOptions, Callback, Context, Throttle } from './types.ts';
+import { getScanContext } from './utils/get-scan-context.js';
+import { recalculatePositions } from './utils/recalculate-positions.js';
+import { recalculateScrollableAncestors } from './utils/recalculate-scrollable-ancestors.js';
+import { createShadowDOMAwareMutationObserver } from './utils/shadow-dom-aware-mutation-observer.js';
+import { supportsAnchorPositioning } from './utils/supports-anchor-positioning.js';
+import { updateElementsWithIssues } from './utils/update-elements-with-issues.js';
+
+export function createScanner(
+  name: string,
+  context: Context,
+  axeOptions: AxeOptions,
+  throttle: Required<Throttle>,
+  callback: Callback,
+) {
   const axeRunningWindowProp = `__${name}_axe_running__`;
-  const win: Record<string, any> = window;
-  const taskQueue = new TaskQueue<Node>(async () => {
+  const win = window as unknown as Record<string, boolean>;
+  const taskQueue = new TaskQueue<Node>(async (nodes) => {
     // We may see errors coming from axe-core when Accented is toggled off and on in qiuck succession,
     // which I've seen happen with hot reloading of a React application.
     // This window property serves as a circuit breaker for that particular case.
@@ -21,50 +29,91 @@ export default function createScanner(name: string, axeContext: AxeContext, axeO
     }
 
     try {
-
-      performance.mark('axe-start');
+      performance.mark('scan-start');
 
       win[axeRunningWindowProp] = true;
 
-      let result;
+      const scanContext = getScanContext(nodes, context);
+
+      let result: axe.AxeResults | undefined;
 
       try {
-        // TODO (https://github.com/pomerantsev/accented/issues/102):
-        // only run Axe on what's changed, not on the whole axeContext
-        result = await axe.run(axeContext, {
+        result = await axe.run(scanContext, {
+          /**
+           * By default, axe-core doesn't include element refs
+           * in the violations array,
+           * and we need those element refs.
+           */
           elementRef: true,
-          // Although axe-core can perform iframe scanning, I haven't succeeded in it,
-          // and the docs suggest that the axe-core script should be explicitly included
-          // in each of the iframed documents anyway.
-          // It seems preferable to disallow iframe scanning and not report issues in elements within iframes
-          // in the case that such issues are for some reason reported by axe-core.
-          // A consumer of Accented can instead scan the iframed document by calling Accented initialization from that document.
+
+          /**
+           * Although axe-core can perform iframe scanning, I haven't succeeded in it,
+           * and the docs suggest that the axe-core script should be explicitly included
+           * in each of the iframed documents anyway.
+           * It seems preferable to disallow iframe scanning and not report issues in elements within iframes
+           * in the case that such issues are for some reason reported by axe-core.
+           * A consumer of Accented can instead scan the iframed document by calling Accented initialization from that document.
+           */
           iframes: false,
+
+          /**
+           * The `preload` docs are not clear to me,
+           * but when it's set to `true` by default,
+           * axe-core tries to fetch cross-origin CSS,
+           * which fails in the absence of CORS headers.
+           * I'm not sure why axe-core needs to preload
+           * those resources in the first place,
+           * so disabling it seems to be the safe option.
+           */
+          preload: false,
+
+          /**
+           * We're only interested in violations,
+           * not in passes or incomplete results.
+           */
           resultTypes: ['violations'],
-          ...axeOptions
+
+          ...axeOptions,
         });
       } catch (error) {
         console.error(
-          'Accented: axe-core (the accessibility testing engine) threw an error. ' +
-            'Check the `axeOptions` property that you’re passing to Accented. ' +
-            `If you still think it’s a bug in Accented, file an issue at ${issuesUrl}.\n`,
-          error
+          `Accented: axe-core (the accessibility testing engine) threw an error. Check the \`axeOptions\` property (https://accented.dev/api#axeoptions) that you’re passing to Accented. If you still think it’s a bug in Accented, file an issue at ${issuesUrl}.\n`,
+          error,
         );
-        result = { violations: [] };
       }
       win[axeRunningWindowProp] = false;
 
-      const axeMeasure = performance.measure('axe', 'axe-start');
+      const scanMeasure = performance.measure('scan', 'scan-start');
+      const scanDuration = Math.round(scanMeasure.duration);
 
-      if (!enabled.value) {
+      if (!enabled.value || !result) {
         return;
       }
 
-      updateElementsWithIssues(extendedElementsWithIssues, result.violations, window, name);
+      performance.mark('dom-update-start');
+
+      updateElementsWithIssues({
+        extendedElementsWithIssues,
+        scanContext,
+        violations: result.violations,
+        win: window,
+        name,
+      });
+
+      const domUpdateMeasure = performance.measure('dom-update', 'dom-update-start');
+      const domUpdateDuration = Math.round(domUpdateMeasure.duration);
 
       callback({
+        // Assuming that the {include, exclude} shape of the context object will be used less often
+        // than other variants, we'll output just the `include` array in case nothing is excluded
+        // in the scan.
+        scanContext: scanContext.exclude.length > 0 ? scanContext : scanContext.include,
         elementsWithIssues: elementsWithIssues.value,
-        scanDuration: Math.round(axeMeasure.duration)
+        performance: {
+          totalBlockingTime: scanDuration + domUpdateDuration,
+          scan: scanDuration,
+          domUpdate: domUpdateDuration,
+        },
       });
     } catch (error) {
       win[axeRunningWindowProp] = false;
@@ -72,21 +121,24 @@ export default function createScanner(name: string, axeContext: AxeContext, axeO
     }
   }, throttle);
 
-  // TODO (https://github.com/pomerantsev/accented/issues/102):
-  // limit to what's in axeContext,
-  // if that's an element or array of elements (not a selector).
   taskQueue.add(document);
 
-  const accentedElementNames = [`${name}-trigger`, `${name}-dialog`];
-  const mutationObserver = new MutationObserver(mutationList => {
+  const accentedElementNames = getAccentedElementNames(name);
+  const mutationObserver = createShadowDOMAwareMutationObserver(name, (mutationList) => {
     try {
       // We're not interested in mutations that are caused exclusively by the custom elements
       // introduced by Accented.
-      const listWithoutAccentedElements = mutationList.filter(mutationRecord => {
-        const onlyAccentedElementsAddedOrRemoved = mutationRecord.type === 'childList' &&
-          [...mutationRecord.addedNodes].every(node => accentedElementNames.includes(node.nodeName.toLowerCase())) &&
-          [...mutationRecord.removedNodes].every(node => accentedElementNames.includes(node.nodeName.toLowerCase()));
-        const accentedElementChanged = mutationRecord.type === 'attributes' &&
+      const listWithoutAccentedElements = mutationList.filter((mutationRecord) => {
+        const onlyAccentedElementsAddedOrRemoved =
+          mutationRecord.type === 'childList' &&
+          [...mutationRecord.addedNodes].every((node) =>
+            accentedElementNames.includes(node.nodeName.toLowerCase()),
+          ) &&
+          [...mutationRecord.removedNodes].every((node) =>
+            accentedElementNames.includes(node.nodeName.toLowerCase()),
+          );
+        const accentedElementChanged =
+          mutationRecord.type === 'attributes' &&
           accentedElementNames.includes(mutationRecord.target.nodeName.toLowerCase());
         return !(onlyAccentedElementsAddedOrRemoved || accentedElementChanged);
       });
@@ -106,31 +158,35 @@ export default function createScanner(name: string, axeContext: AxeContext, axeO
       // If we simply exclude all mutations where attributeName = `data-${name}`,
       // we may miss other mutations on those same elements caused by Accented,
       // leading to extra runs of the mutation observer.
-      const elementsWithAccentedAttributeChanges = listWithoutAccentedElements.reduce((nodes, mutationRecord) => {
-        if (mutationRecord.type === 'attributes' && mutationRecord.attributeName === `data-${name}`) {
-          nodes.add(mutationRecord.target);
-        }
-        return nodes;
-      }, new Set<Node>());
-
-      const filteredMutationList = listWithoutAccentedElements.filter(mutationRecord => {
+      const elementsWithAccentedAttributeChanges = listWithoutAccentedElements.reduce(
+        (nodes, mutationRecord) => {
+          if (
+            mutationRecord.type === 'attributes' &&
+            mutationRecord.attributeName === `data-${name}`
+          ) {
+            nodes.add(mutationRecord.target);
+          }
+          return nodes;
+        },
+        new Set<Node>(),
+      );
+
+      const filteredMutationList = listWithoutAccentedElements.filter((mutationRecord) => {
         return !elementsWithAccentedAttributeChanges.has(mutationRecord.target);
       });
 
-      taskQueue.addMultiple(filteredMutationList.map(mutationRecord => mutationRecord.target));
+      const nodes = filteredMutationList.map((mutationRecord) => mutationRecord.target);
+      taskQueue.addMultiple(nodes);
     } catch (error) {
       logAndRethrow(error);
     }
   });
 
-  // TODO (https://github.com/pomerantsev/accented/issues/102):
-  // possibly limit the observer to what's in axeContext,
-  // if that's an element or array of elements (not a selector).
   mutationObserver.observe(document, {
     subtree: true,
     childList: true,
     attributes: true,
-    characterData: true
+    characterData: true,
   });
 
   return () => {

package/src/scroll-listeners.ts

@@ -1,37 +1,45 @@
 import { effect } from '@preact/signals-core';
-import recalculatePositions from './utils/recalculate-positions.js';
+import { logAndRethrow } from './log-and-rethrow.js';
 import { scrollableAncestors } from './state.js';
-import logAndRethrow from './log-and-rethrow.js';
+import { recalculatePositions } from './utils/recalculate-positions.js';
 
-export default function setupScrollListeners() {
+export function setupScrollListeners() {
   const documentAbortController = new AbortController();
-  document.addEventListener('scroll', () => {
-    try {
-      recalculatePositions();
-    } catch (error) {
-      logAndRethrow(error);
-    }
-  }, { signal: documentAbortController.signal });
+  document.addEventListener(
+    'scroll',
+    () => {
+      try {
+        recalculatePositions();
+      } catch (error) {
+        logAndRethrow(error);
+      }
+    },
+    { signal: documentAbortController.signal },
+  );
 
   const disposeOfEffect = effect(() => {
     // TODO: optimize performance, issue #81
     const elementAbortController = new AbortController();
     for (const scrollableAncestor of scrollableAncestors.value) {
-      scrollableAncestor.addEventListener('scroll', () => {
-        try {
-          recalculatePositions();
-        } catch (error) {
-          logAndRethrow(error);
-        }
-      }, { signal: elementAbortController.signal });
+      scrollableAncestor.addEventListener(
+        'scroll',
+        () => {
+          try {
+            recalculatePositions();
+          } catch (error) {
+            logAndRethrow(error);
+          }
+        },
+        { signal: elementAbortController.signal },
+      );
     }
     return () => {
       elementAbortController.abort();
-    }
+    };
   });
 
   return () => {
     documentAbortController.abort();
     disposeOfEffect();
   };
-};
+}

package/src/state.ts

@@ -1,24 +1,35 @@
-import { signal, computed } from '@preact/signals-core';
+import { computed, signal } from '@preact/signals-core';
 
-import type { ElementWithIssues, ExtendedElementWithIssues } from './types';
+import type { ElementWithIssues, ExtendedElementWithIssues } from './types.ts';
 
 export const enabled = signal(false);
 
 export const extendedElementsWithIssues = signal<Array<ExtendedElementWithIssues>>([]);
 
-export const elementsWithIssues = computed<Array<ElementWithIssues>>(() => extendedElementsWithIssues.value.map(extendedElementWithIssues => ({
-  element: extendedElementWithIssues.element,
-  issues: extendedElementWithIssues.issues.value
-})));
+export const elementsWithIssues = computed<Array<ElementWithIssues>>(() =>
+  extendedElementsWithIssues.value.map((extendedElementWithIssues) => ({
+    element: extendedElementWithIssues.element,
+    rootNode: extendedElementWithIssues.rootNode,
+    issues: extendedElementWithIssues.issues.value,
+  })),
+);
+
+export const rootNodes = computed<Set<Node>>(
+  () =>
+    new Set(
+      (enabled.value ? [document as Node] : []).concat(
+        ...extendedElementsWithIssues.value.map(
+          (extendedElementWithIssues) => extendedElementWithIssues.rootNode,
+        ),
+      ),
+    ),
+);
 
-export const scrollableAncestors = computed<Set<HTMLElement>>(() =>
-  extendedElementsWithIssues.value.reduce(
-    (scrollableAncestors, extendedElementWithIssues) => {
-      for (const scrollableAncestor of extendedElementWithIssues.scrollableAncestors.value) {
-        scrollableAncestors.add(scrollableAncestor);
-      }
-      return scrollableAncestors;
-    },
-    new Set<HTMLElement>()
-  )
+export const scrollableAncestors = computed<Set<Element>>(() =>
+  extendedElementsWithIssues.value.reduce((scrollableAncestors, extendedElementWithIssues) => {
+    for (const scrollableAncestor of extendedElementWithIssues.scrollableAncestors.value) {
+      scrollableAncestors.add(scrollableAncestor);
+    }
+    return scrollableAncestors;
+  }, new Set<Element>()),
 );

package/src/task-queue.test.ts

@@ -1,11 +1,12 @@
 import assert from 'node:assert/strict';
-import {mock, suite, test} from 'node:test';
+import { mock, suite, test } from 'node:test';
 
-import TaskQueue from './task-queue.js';
+import { TaskQueue } from './task-queue';
 
-const wait = (duration: number) => new Promise(resolve => setTimeout(resolve, duration));
+const wait = (duration: number) => new Promise((resolve) => setTimeout(resolve, duration));
 
-const createAsyncCallback = (duration: number) => mock.fn(() => new Promise(resolve => setTimeout(resolve, duration)));
+const createAsyncCallback = (duration: number) =>
+  mock.fn(() => new Promise((resolve) => setTimeout(resolve, duration)));
 
 suite('TaskQueue', () => {
   test('callback is not called after a TaskQueue is created, even after a timeout', async () => {

package/src/task-queue.ts

@@ -1,15 +1,15 @@
-import type { Throttle } from './types';
+import type { Throttle } from './types.ts';
 
-type TaskCallback = () => void;
+type TaskCallback<T> = (items: Array<T>) => void;
 
-export default class TaskQueue<T> {
+export class TaskQueue<T> {
   #throttle: Throttle;
-  #asyncCallback: TaskCallback | null = null;
+  #asyncCallback: TaskCallback<T> | null = null;
 
   #items = new Set<T>();
   #inRunLoop = false;
 
-  constructor(asyncCallback: TaskCallback, throttle: Required<Throttle>) {
+  constructor(asyncCallback: TaskCallback<T>, throttle: Required<Throttle>) {
     this.#asyncCallback = asyncCallback;
     this.#throttle = throttle;
   }
@@ -33,10 +33,12 @@ export default class TaskQueue<T> {
       return;
     }
 
+    const items = Array.from(this.#items);
+
     this.#items.clear();
 
     if (this.#asyncCallback) {
-      await this.#asyncCallback();
+      await this.#asyncCallback(items);
     }
 
     await new Promise((resolve) => setTimeout(resolve, this.#throttle.wait));