accented 0.0.1-dev.3 → 0.0.2

package/src/log-and-rethrow.ts

@@ -0,0 +1,9 @@
+import { issuesUrl } from './constants.js';
+
+export default function logAndRethrow(error: unknown) {
+  console.error(
+    `Accented threw an error (see below). Try updating your browser to the latest version. ` +
+      `If you’re still seeing the error, file an issue at ${issuesUrl}.`
+  );
+  throw error;
+}

package/src/logger.ts

@@ -0,0 +1,26 @@
+import { effect } from '@preact/signals-core';
+import { elementsWithIssues, enabled } from './state.js';
+import { accentedUrl } from './constants.js';
+
+export default function createLogger() {
+
+  let firstRun = true;
+
+  return effect(() => {
+    if (!enabled.value) {
+      return;
+    }
+
+    const elementCount = elementsWithIssues.value.length;
+    if (elementCount > 0) {
+      const issueCount = elementsWithIssues.value.reduce((acc, { issues }) => acc + issues.length, 0);
+      console.log(`${issueCount} accessibility issue${issueCount === 1 ? '' : 's'} found in ${elementCount} element${issueCount === 1 ? '' : 's'} (Accented, ${accentedUrl}):\n`, elementsWithIssues.value);
+    } else {
+      if (firstRun) {
+        firstRun = false;
+      } else {
+        console.log(`No accessibility issues found (Accented, ${accentedUrl}).`);
+      }
+    }
+  });
+}

package/src/register-elements.ts

@@ -0,0 +1,21 @@
+import getAccentedTrigger from './elements/accented-trigger.js';
+import getAccentedDialog from './elements/accented-dialog.js';
+
+export default function registerElements(name: string): void {
+  const elements = [
+    {
+      elementName: `${name}-trigger`,
+      Component: getAccentedTrigger(name)
+    },
+    {
+      elementName: `${name}-dialog`,
+      Component: getAccentedDialog()
+    }
+  ];
+
+  for (const { elementName, Component } of elements) {
+    if (!customElements.get(elementName)) {
+      customElements.define(elementName, Component);
+    }
+  }
+};

package/src/resize-listener.ts

@@ -0,0 +1,17 @@
+import logAndRethrow from './log-and-rethrow.js';
+import recalculatePositions from './utils/recalculate-positions.js';
+
+export default function setupResizeListener() {
+  const abortController = new AbortController();
+  window.addEventListener('resize', () => {
+    try {
+      recalculatePositions();
+    } catch (error) {
+      logAndRethrow(error);
+    }
+  }, { signal: abortController.signal });
+
+  return () => {
+    abortController.abort();
+  };
+};

package/src/scanner.ts

@@ -0,0 +1,139 @@
+import axe from 'axe-core';
+import TaskQueue from './task-queue.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) {
+  const axeRunningWindowProp = `__${name}_axe_running__`;
+  const win: Record<string, any> = window;
+  const taskQueue = new TaskQueue<Node>(async () => {
+    // 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;
+    }
+
+    try {
+
+      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 => {
+    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();
+      }
+
+      // 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));
+    } 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
+  });
+
+  return () => {
+    mutationObserver.disconnect();
+  };
+}

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

@@ -0,0 +1,24 @@
+import { signal, computed } from '@preact/signals-core';
+
+import type { ElementWithIssues, ExtendedElementWithIssues } from './types';
+
+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 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/task-queue.test.ts

@@ -0,0 +1,135 @@
+import assert from 'node:assert/strict';
+import {mock, suite, test} from 'node:test';
+
+import TaskQueue from './task-queue.js';
+
+const wait = (duration: number) => 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 () => {
+    const asyncCallback = createAsyncCallback(0);
+    new TaskQueue(asyncCallback, { wait: 50, leading: true });
+    await wait(100);
+    assert.equal(asyncCallback.mock.callCount(), 0);
+  });
+
+  test('callback is not called if addMultiple is called with an empty array', async () => {
+    const asyncCallback = createAsyncCallback(0);
+    const taskQueue = new TaskQueue(asyncCallback, { wait: 50, leading: true });
+    taskQueue.addMultiple([]);
+    await wait(100);
+    assert.equal(asyncCallback.mock.callCount(), 0);
+  });
+
+  test('callback is called once if multiple items are added before the first delay has elapsed', async () => {
+    const asyncCallback = createAsyncCallback(0);
+    const taskQueue = new TaskQueue<string>(asyncCallback, { wait: 100, leading: false });
+    taskQueue.add('one');
+    // Adding the second item synchronously
+    taskQueue.add('two');
+    await wait(50);
+    // Adding the third item asynchronously
+    taskQueue.add('three');
+    assert.equal(asyncCallback.mock.callCount(), 0);
+    await wait(100);
+    assert.equal(asyncCallback.mock.callCount(), 1);
+  });
+
+  test('callback is called according to expected schedule', async () => {
+    const asyncCallback = createAsyncCallback(100);
+    const taskQueue = new TaskQueue<string>(asyncCallback, { wait: 100, leading: false });
+
+    // 0 ms: Add "one"
+    taskQueue.add('one');
+
+    await wait(50);
+
+    // 50 ms: First measurement, callback not called
+    assert.equal(asyncCallback.mock.callCount(), 0);
+
+    // 100 ms: Callback called for the first time
+    // 200 ms: First callback completes
+
+    await wait(200);
+
+    // 250 ms: Second measurement, callback called once
+    assert.equal(asyncCallback.mock.callCount(), 1);
+
+    // 250 ms: Add "two"
+    taskQueue.add('two');
+
+    // 350 ms: Callback called for the second time
+
+    await wait(150);
+
+    // 400 ms: Third measurement, callback called twice
+    assert.equal(asyncCallback.mock.callCount(), 2);
+  });
+
+  test('callback is called according to expected schedule when second task is added before the first callback completes', async () => {
+    const asyncCallback = createAsyncCallback(100);
+    const taskQueue = new TaskQueue<string>(asyncCallback, { wait: 100, leading: false });
+
+    // 0 ms: Add "one"
+    taskQueue.add('one');
+
+    await wait(50);
+
+    // 50 ms: First measurement, callback not called
+    assert.equal(asyncCallback.mock.callCount(), 0);
+
+    // 100 ms: Callback called for the first time
+
+    await wait(100);
+
+    // 150 ms: Second measurement, callback called once
+    assert.equal(asyncCallback.mock.callCount(), 1);
+
+    // 150 ms: Add "two"
+    taskQueue.add('two');
+
+    // 200 ms: First callback completes
+
+    await wait(100);
+
+    // 250 ms: Third measurement, callback still called only once
+    assert.equal(asyncCallback.mock.callCount(), 1);
+
+    // 300 ms: Callback called for the second time
+
+    await wait(100);
+
+    // 350 ms: Fourth measurement, callback called twice
+    assert.equal(asyncCallback.mock.callCount(), 2);
+  });
+
+  test('callback is called according to expected schedule with leading: true', async () => {
+    const asyncCallback = createAsyncCallback(100);
+    const taskQueue = new TaskQueue<string>(asyncCallback, { wait: 100, leading: true });
+
+    // 0 ms: Add "one"
+    taskQueue.add('one');
+
+    await wait(50);
+
+    // 50 ms: Add "two"
+    taskQueue.add('two');
+
+    // 50 ms: First measurement, callback called
+    assert.equal(asyncCallback.mock.callCount(), 1);
+
+    // 100 ms: First callback completes
+
+    await wait(100);
+
+    // 150 ms: Second measurement, callback still called once
+    assert.equal(asyncCallback.mock.callCount(), 1);
+
+    await wait(100);
+
+    // 250 ms: Third measurement, callback called twice
+    assert.equal(asyncCallback.mock.callCount(), 2);
+  });
+});

package/src/task-queue.ts

@@ -0,0 +1,59 @@
+import type { Throttle } from './types';
+
+type TaskCallback = () => void;
+
+export default class TaskQueue<T> {
+  #throttle: Throttle;
+  #asyncCallback: TaskCallback | null = null;
+
+  #items = new Set<T>();
+  #inRunLoop = false;
+
+  constructor(asyncCallback: TaskCallback, throttle: Required<Throttle>) {
+    this.#asyncCallback = asyncCallback;
+    this.#throttle = throttle;
+  }
+
+  async #preRun() {
+    if (this.#inRunLoop) {
+      return;
+    }
+    this.#inRunLoop = true;
+
+    if (!this.#throttle.leading) {
+      await new Promise((resolve) => setTimeout(resolve, this.#throttle.wait));
+    }
+
+    await this.#run();
+  }
+
+  async #run() {
+    if (this.#items.size === 0) {
+      this.#inRunLoop = false;
+      return;
+    }
+
+    this.#items.clear();
+
+    if (this.#asyncCallback) {
+      await this.#asyncCallback();
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, this.#throttle.wait));
+
+    await this.#run();
+  }
+
+  addMultiple(items: Array<T>) {
+    for (const item of items) {
+      this.#items.add(item);
+    }
+    if (this.#items.size > 0) {
+      this.#preRun();
+    }
+  }
+
+  add(item: T) {
+    this.addMultiple([item]);
+  }
+}

package/src/types.ts

@@ -0,0 +1,155 @@
+import type axe from 'axe-core';
+import type { Signal } from '@preact/signals-core';
+import type { AccentedTrigger } from './elements/accented-trigger';
+
+export type Throttle = {
+  /**
+   * The minimal time between scans.
+   *
+   * 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.
+   *
+   * 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.
+   * */
+  elementsWithIssues: Array<ElementWithIssues>,
+
+  /**
+   * How long the scan took in milliseconds.
+   * */
+  scanDuration: number
+}
+
+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 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__`).
+   *
+   * Only lowercase alphanumeric characters and dashes (-) are allowed in the name,
+   * and it must start with a lowercase letter.
+   *
+   * Default: `accented`.
+   */
+  name?: string,
+
+  /**
+   * Output options object.
+   * */
+  output?: Output,
+
+  /**
+   * Scan throttling options object.
+   * */
+  throttle?: Throttle,
+
+  /**
+   * A callback that will be called after each scan.
+   *
+   * Default: `() => {}`.
+   * */
+  callback?: Callback
+};
+
+/**
+ * A function that fully disables Accented,
+ * stopping the scanning and removing all highlights from the page.
+ */
+export type DisableAccented = () => void;
+
+export type Position = {
+  inlineEndLeft: number,
+  blockStartTop: number,
+  direction: 'ltr' | 'rtl'
+};
+
+export type Issue = {
+  id: string,
+  title: string,
+  description: string,
+  url: string,
+  impact: axe.ImpactValue
+};
+
+export type ElementWithIssues = {
+  element: HTMLElement,
+  issues: Array<Issue>
+}
+
+export type ExtendedElementWithIssues = Omit<ElementWithIssues, 'issues'> & {
+  issues: Signal<ElementWithIssues['issues']>,
+  visible: Signal<boolean>,
+  trigger: AccentedTrigger,
+  position: Signal<Position>,
+  scrollableAncestors: Signal<Set<HTMLElement>>
+  id: number
+};

package/src/utils/are-issue-sets-equal.test.ts

@@ -0,0 +1,49 @@
+import assert from 'node:assert/strict';
+import {suite, test} from 'node:test';
+import areIssueSetsEqual from './are-issue-sets-equal.js';
+import type { Issue } from '../types';
+
+const issue1: Issue = {
+  id: 'id1',
+  title: 'title1',
+  description: 'description1',
+  url: 'http://example.com',
+  impact: 'serious'
+};
+
+const issue2: Issue = {
+  id: 'id2',
+  title: 'title2',
+  description: 'description2',
+  url: 'http://example.com',
+  impact: 'serious'
+};
+
+// @ts-expect-error
+const issue2Clone: Issue = Object.keys(issue2).reduce((obj, key) => { obj[key] = issue2[key]; return obj; }, {});
+
+const issue3: Issue = {
+  id: 'id3',
+  title: 'title3',
+  description: 'description3',
+  url: 'http://example.com',
+  impact: 'serious'
+};
+
+suite('areIssueSetsEqual', () => {
+  test('returns true when both sets are empty', () => {
+    assert.ok(areIssueSetsEqual([], []));
+  });
+
+  test('returns true when both sets have equal elements, even when the order in the arrays doesn’t match', () => {
+    assert.ok(areIssueSetsEqual([issue1, issue2], [issue2Clone, issue1]));
+  });
+
+  test('returns false when sets have different length', () => {
+    assert.equal(areIssueSetsEqual([issue1, issue2], [issue1]), false);
+  });
+
+  test('returns false when sets have the same length, but one element differs', () => {
+    assert.equal(areIssueSetsEqual([issue1, issue2], [issue1, issue3]), false);
+  });
+});

package/src/utils/are-issue-sets-equal.ts

@@ -0,0 +1,10 @@
+import type { Issue } from '../types';
+
+const issueProps: Array<keyof Issue> = ['id', 'title', 'description', 'url', 'impact'];
+
+export default function areIssueSetsEqual(issues1: Array<Issue>, issues2: Array<Issue>) {
+  return issues1.length === issues2.length &&
+    issues1.every(issue1 => Boolean(issues2.find(issue2 =>
+      issueProps.every(prop => issue2[prop] === issue1[prop])
+    )));
+}