accented 0.0.0-20250124142030 → 0.0.0-20250223121749

package/src/scanner.ts

@@ -1,60 +1,131 @@
 import axe from 'axe-core';
 import TaskQueue from './task-queue.js';
 import { elementsWithIssues, enabled, extendedElementsWithIssues } from './state.js';
-import type { Throttle, Callback } from './types';
+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, throttle: Required<Throttle>, callback: Callback) {
+export default function createScanner(name: string, axeContext: AxeContext, axeOptions: AxeOptions, throttle: Required<Throttle>, callback: Callback) {
+  const axeRunningWindowProp = `__${name}_axe_running__`;
+  const win: Record<string, any> = window;
   const taskQueue = new TaskQueue<Node>(async () => {
-    performance.mark('axe-start');
-    const result = await axe.run({
-      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.
-      iframes: false
-    });
-
-    const axeMeasure = performance.measure('axe', 'axe-start');
-
-    if (!enabled.value) {
+    // 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.
+    if (win[axeRunningWindowProp]) {
       return;
     }
 
-    updateElementsWithIssues(extendedElementsWithIssues, result.violations, window, name);
+    try {
 
-    callback({
-      elementsWithIssues: elementsWithIssues.value,
-      scanDuration: Math.round(axeMeasure.duration)
-    });
+      performance.mark('axe-start');
+
+      win[axeRunningWindowProp] = true;
+
+      let result;
+
+      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, {
+          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.
+          iframes: false,
+          resultTypes: ['violations'],
+          ...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
+        );
+        result = { violations: [] };
+      }
+      win[axeRunningWindowProp] = false;
+
+      const axeMeasure = performance.measure('axe', 'axe-start');
+
+      if (!enabled.value) {
+        return;
+      }
+
+      updateElementsWithIssues(extendedElementsWithIssues, result.violations, window, name);
+
+      callback({
+        elementsWithIssues: elementsWithIssues.value,
+        scanDuration: Math.round(axeMeasure.duration)
+      });
+    } catch (error) {
+      win[axeRunningWindowProp] = false;
+      logAndRethrow(error);
+    }
   }, 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 listWithoutAccentedContainers = mutationList.filter(mutationRecord => {
-      return !(mutationRecord.type === 'childList' &&
-        [...mutationRecord.addedNodes].every(node => node.nodeName === `${name}-container`.toUpperCase()) &&
-        [...mutationRecord.removedNodes].every(node => node.nodeName === `${name}-container`.toUpperCase()));
-    });
-
-    const elementsWithAccentedAttributeChanges = listWithoutAccentedContainers.reduce((nodes, mutationRecord) => {
-      if (mutationRecord.type === 'attributes' && mutationRecord.attributeName === `data-${name}`) {
-        nodes.add(mutationRecord.target);
+    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' &&
+          accentedElementNames.includes(mutationRecord.target.nodeName.toLowerCase());
+        return !(onlyAccentedElementsAddedOrRemoved || accentedElementChanged);
+      });
+
+      if (listWithoutAccentedElements.length !== 0 && !supportsAnchorPositioning(window)) {
+        // Something has changed in the DOM, so we need to realign all triggers with respective elements.
+        recalculatePositions();
+
+        // Elements' scrollable ancestors only change when styles change
+        // (specifically when the `display` prop on one of the ancestors changes),
+        // so a good place to recalculate the scrollable ancestors for elements is here.
+        // In future, we could further optimize this by only recalculating scrollable ancestors for elements that have changed.
+        recalculateScrollableAncestors();
       }
-      return nodes;
-    }, new Set<Node>());
 
-    const filteredMutationList = listWithoutAccentedContainers.filter(mutationRecord => {
-      return !elementsWithAccentedAttributeChanges.has(mutationRecord.target);
-    });
+      // Exclude all mutations on elements that got the accented attribute added or removed.
+      // 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 => {
+        return !elementsWithAccentedAttributeChanges.has(mutationRecord.target);
+      });
 
-    taskQueue.addMultiple(filteredMutationList.map(mutationRecord => mutationRecord.target));
+      taskQueue.addMultiple(filteredMutationList.map(mutationRecord => mutationRecord.target));
+    } 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,

package/src/scroll-listeners.ts

@@ -0,0 +1,37 @@
+import { effect } from '@preact/signals-core';
+import recalculatePositions from './utils/recalculate-positions.js';
+import { scrollableAncestors } from './state.js';
+import logAndRethrow from './log-and-rethrow.js';
+
+export default function setupScrollListeners() {
+  const documentAbortController = new AbortController();
+  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 });
+    }
+    return () => {
+      elementAbortController.abort();
+    }
+  });
+
+  return () => {
+    documentAbortController.abort();
+    disposeOfEffect();
+  };
+};

package/src/state.ts

@@ -10,3 +10,15 @@ export const elementsWithIssues = computed<Array<ElementWithIssues>>(() => exten
   element: extendedElementWithIssues.element,
   issues: extendedElementWithIssues.issues.value
 })));
+
+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>()
+  )
+);

package/src/types.ts

@@ -1,29 +1,40 @@
 import type axe from 'axe-core';
 import type { Signal } from '@preact/signals-core';
-import type { AccentedContainer } from './elements/accented-container';
-
-export type DeepRequired<T> = T extends object ? {
-  [P in keyof T]-? : DeepRequired<T[P]>
-} : T;
+import type { AccentedTrigger } from './elements/accented-trigger';
 
 export type Throttle = {
   /**
    * The minimal time between scans.
    *
-   * Default: 1000.
+   * Default: `1000`.
    * */
   wait?: number,
 
   /**
    * When to run the scan on Accented initialization or on a mutation.
    *
-   * If true, the scan will run immediately. If false, the scan will run after the first throttle delay.
+   * If `true`, the scan will run immediately. If `false`, the scan will run after the first throttle delay.
    *
-   * Default: true.
+   * Default: `true`.
    * */
   leading?: boolean
 }
 
+export type Output = {
+  /**
+   * Whether to output the issues to the console.
+   *
+   * Default: `true`.
+   * */
+  console?: boolean
+}
+
+export type AxeContext = axe.ElementContext;
+
+export const allowedAxeOptions = ['rules', 'runOnly'] as const;
+
+export type AxeOptions = Pick<axe.RunOptions, typeof allowedAxeOptions[number]>;
+
 type CallbackParams = {
   /**
    * The most current array of elements with issues.
@@ -40,23 +51,61 @@ export type Callback = (params: CallbackParams) => void;
 
 export type AccentedOptions = {
 
+  /**
+   * The `context` parameter for `axe.run()`.
+   *
+   * Determines what element(s) to scan for accessibility issues.
+   *
+   * Accepts a variety of shapes:
+   * * an element reference;
+   * * a selector;
+   * * a `NodeList`;
+   * * an include / exclude object;
+   * * and more.
+   *
+   * See documentation: https://www.deque.com/axe/core-documentation/api-documentation/#context-parameter
+   *
+   * Default: `document`.
+   */
+  axeContext?: AxeContext,
+
+  /**
+   * The `options` parameter for `axe.run()`.
+   *
+   * Accented only supports two keys of the `options` object:
+   * * `rules`;
+   * * `runOnly`.
+   *
+   * Both properties are optional, and both control
+   * which accessibility rules your page is tested against.
+   *
+   * See documentation: https://www.deque.com/axe/core-documentation/api-documentation/#options-parameter
+   *
+   * Default: `{}`.
+   */
+  axeOptions?: AxeOptions,
+
   /**
    * The character sequence that’s used in various elements, attributes and stylesheets that Accented adds to the page.
-   * * The data attribute that’s added to elements with issues (default: "data-accented").
-   * * The custom element that encapsulates the button and dialog attached to each element with issues (default: "accented-container").
-   * * The CSS cascade layer containing page-wide Accented-specific styles (default: "accented").
-   * * The prefix for some of the CSS custom properties used by Accented (default: "--accented-").
+   * * The data attribute that’s added to elements with issues (default: `data-accented`).
+   * * The custom elements for the button and the dialog that get created for each element with issues
+   *   (default: `accented-trigger`, `accented-dialog`).
+   * * The CSS cascade layer containing page-wide Accented-specific styles (default: `accented`).
+   * * The prefix for some of the CSS custom properties used by Accented (default: `--accented-`).
+   * * The window property that’s used to prevent multiple axe-core scans from running simultaneously
+   *   (default: `__accented_axe_running__`).
    *
-   * Default: "accented".
+   * Only lowercase alphanumeric characters and dashes (-) are allowed in the name,
+   * and it must start with a lowercase letter.
+   *
+   * Default: `accented`.
    */
   name?: string,
 
   /**
-   * Whether to output the issues to the console.
-   *
-   * Default: true.
+   * Output options object.
    * */
-  outputToConsole?: boolean,
+  output?: Output,
 
   /**
    * Scan throttling options object.
@@ -66,7 +115,7 @@ export type AccentedOptions = {
   /**
    * A callback that will be called after each scan.
    *
-   * Default: () => {}.
+   * Default: `() => {}`.
    * */
   callback?: Callback
 };
@@ -77,6 +126,12 @@ export type AccentedOptions = {
  */
 export type DisableAccented = () => void;
 
+export type Position = {
+  inlineEndLeft: number,
+  blockStartTop: number,
+  direction: 'ltr' | 'rtl'
+};
+
 export type Issue = {
   id: string,
   title: string,
@@ -92,6 +147,9 @@ export type ElementWithIssues = {
 
 export type ExtendedElementWithIssues = Omit<ElementWithIssues, 'issues'> & {
   issues: Signal<ElementWithIssues['issues']>,
-  accentedContainer: AccentedContainer,
+  visible: Signal<boolean>,
+  trigger: AccentedTrigger,
+  position: Signal<Position>,
+  scrollableAncestors: Signal<Set<HTMLElement>>
   id: number
 };

package/src/utils/deep-merge.test.ts

@@ -24,4 +24,11 @@ suite('deepMerge', () => {
     const result = deepMerge(target, source);
     assert.deepEqual(result, { a: null });
   });
+
+  test('doesn’t turn arrays into objects', () => {
+    const target = { a: [1, 2, 3] };
+    const source = { a: [4, 5] };
+    const result = deepMerge(target, source);
+    assert.deepEqual(result, { a: [4, 5] });
+  });
 });

package/src/utils/deep-merge.ts

@@ -3,7 +3,7 @@ type AnyObject = Record<string, any>;
 export default function deepMerge(target: AnyObject, source: AnyObject): AnyObject {
   const output = {...target};
   for (const key of Object.keys(source)) {
-    if (typeof source[key] === 'object' && source[key] !== null) {
+    if (typeof source[key] === 'object' && source[key] !== null && !Array.isArray(source[key])) {
       if (!(key in target)) {
         output[key] = source[key];
       } else {

package/src/utils/get-element-html.ts

@@ -0,0 +1,13 @@
+export default function getElementHtml(element: Element) {
+  const outerHtml = element.outerHTML;
+  const innerHtml = element.innerHTML;
+  if (!innerHtml) {
+    return outerHtml;
+  }
+  const index = outerHtml.indexOf(innerHtml);
+  if (index === -1) {
+    // This shouldn't be happening, but if it does, we can just return the outer HTML.
+    return outerHtml;
+  }
+  return outerHtml.slice(0, index) + '…' + outerHtml.slice(index + innerHtml.length);
+}

package/src/utils/get-element-position.ts

@@ -0,0 +1,21 @@
+import type { Position } from '../types';
+
+export default function getElementPosition(element: Element, win: Window): Position {
+  const rect = element.getBoundingClientRect();
+  const direction = win.getComputedStyle(element).direction;
+  if (direction === 'ltr') {
+    return {
+      inlineEndLeft: rect.right,
+      blockStartTop: rect.top,
+      direction
+    };
+  } else if (direction === 'rtl') {
+    return {
+      inlineEndLeft: rect.left,
+      blockStartTop: rect.top,
+      direction
+    };
+  } else {
+    throw new Error(`The element ${element} has a direction "${direction}", which is not supported.`);
+  }
+}

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

@@ -0,0 +1,14 @@
+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;
+    const computedStyle = win.getComputedStyle(currentElement);
+    if (scrollableOverflowValues.has(computedStyle.overflowX) || scrollableOverflowValues.has(computedStyle.overflowY)) {
+      scrollableAncestors.add(currentElement);
+    }
+  }
+  return scrollableAncestors;
+};

package/src/utils/recalculate-positions.ts

@@ -0,0 +1,27 @@
+import { batch } from '@preact/signals-core';
+import { extendedElementsWithIssues } from '../state.js';
+import getElementPosition from './get-element-position.js';
+import logAndRethrow from '../log-and-rethrow.js';
+
+let frameRequested = false;
+
+export default function recalculatePositions() {
+  if (frameRequested) {
+    return;
+  }
+  frameRequested = true;
+  window.requestAnimationFrame(() => {
+    try {
+      frameRequested = false;
+      batch(() => {
+        extendedElementsWithIssues.value.forEach(({ element, position, visible }) => {
+          if (visible.value && element.isConnected) {
+            position.value = getElementPosition(element, window);
+          }
+        });
+      });
+    } catch (error) {
+      logAndRethrow(error);
+    }
+  });
+}

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

@@ -0,0 +1,13 @@
+import { batch } from '@preact/signals-core';
+import { extendedElementsWithIssues } from '../state.js';
+import getScrollableAncestors from './get-scrollable-ancestors.js';
+
+export default function recalculateScrollableAncestors() {
+  batch(() => {
+    extendedElementsWithIssues.value.forEach(({ element, scrollableAncestors }) => {
+      if (element.isConnected) {
+        scrollableAncestors.value = getScrollableAncestors(element, window);
+      }
+    });
+  });
+}

package/src/utils/supports-anchor-positioning.ts

@@ -0,0 +1,7 @@
+type WindowWithCSS = Window & {
+  CSS: typeof CSS
+}
+
+export default function supportsAnchorPositioning(win: WindowWithCSS) {
+  return win.CSS.supports('anchor-name: --foo') && win.CSS.supports('position-anchor: --foo');
+}

package/src/utils/transform-violations.ts

@@ -1,6 +1,11 @@
-import type { AxeResults } from 'axe-core';
+import type { AxeResults, ImpactValue } from 'axe-core';
 import type { Issue, ElementWithIssues } from '../types';
 
+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) {
   const elementsWithIssues: Array<ElementWithIssues> = [];
 
@@ -41,5 +46,11 @@ export default function transformViolations(violations: typeof AxeResults.violat
     }
   }
 
+  for (const elementWithIssues of elementsWithIssues) {
+    elementWithIssues.issues.sort((a, b) => {
+      return -impactCompare(a.impact, b.impact) || a.id.localeCompare(b.id);
+    });
+  }
+
   return elementsWithIssues;
 }