accented 0.0.1-dev.4 → 1.0.0

package/src/intersection-observer.ts

@@ -0,0 +1,39 @@
+import { logAndRethrow } from './log-and-rethrow.js';
+import { extendedElementsWithIssues } from './state.js';
+import { getElementPosition } from './utils/get-element-position.js';
+import { supportsAnchorPositioning } from './utils/supports-anchor-positioning.js';
+
+export function setupIntersectionObserver() {
+  const intersectionObserver = new IntersectionObserver(
+    (entries) => {
+      try {
+        for (const entry of entries) {
+          const extendedElementWithIssues = extendedElementsWithIssues.value.find(
+            (el) => el.element === entry.target,
+          );
+          if (extendedElementWithIssues) {
+            // We initially treated setting visibility in the intersection observer
+            // as a fallback option for browsers that don't support `position-visibility`,
+            // but then we realized that this `position-visibility` actually works
+            // in an unexpected way when the container has `overflow: visible`.
+            // So now we always set visibility in the intersection observer.
+            extendedElementWithIssues.visible.value = entry.isIntersecting;
+            if (entry.isIntersecting && !supportsAnchorPositioning(window)) {
+              extendedElementWithIssues.position.value = getElementPosition(entry.target, window);
+            }
+          }
+        }
+      } catch (error) {
+        logAndRethrow(error);
+      }
+    },
+    { threshold: 0 },
+  );
+
+  return {
+    intersectionObserver,
+    disconnect: () => {
+      intersectionObserver.disconnect();
+    },
+  };
+}

package/src/log-and-rethrow.ts

@@ -0,0 +1,8 @@
+import { issuesUrl } from './constants.js';
+
+export 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,36 @@
+import { effect } from '@preact/signals-core';
+import { accentedUrl } from './constants.js';
+import { elementsWithIssues, enabled } from './state.js';
+import type { ElementWithIssues } from './types.ts';
+
+function filterPropsForOutput(elements: Array<ElementWithIssues>) {
+  return elements.map(({ element, issues }) => ({ element, issues }));
+}
+
+export 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`,
+        filterPropsForOutput(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 { getAccentedDialog } from './elements/accented-dialog.js';
+import { getAccentedTrigger } from './elements/accented-trigger.js';
+
+export 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,21 @@
+import { logAndRethrow } from './log-and-rethrow.js';
+import { recalculatePositions } from './utils/recalculate-positions.js';
+
+export 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,195 @@
+import axe from 'axe-core';
+import { getAccentedElementNames, issuesUrl } from './constants.js';
+import { logAndRethrow } from './log-and-rethrow.js';
+import { elementsWithIssues, enabled, extendedElementsWithIssues } from './state.js';
+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 = 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.
+    if (win[axeRunningWindowProp]) {
+      return;
+    }
+
+    try {
+      performance.mark('scan-start');
+
+      win[axeRunningWindowProp] = true;
+
+      const scanContext = getScanContext(nodes, context);
+
+      let result: axe.AxeResults | undefined;
+
+      try {
+        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.
+           */
+          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,
+        });
+      } catch (error) {
+        console.error(
+          `Accented: axe-core (the accessibility testing engine) threw an error. Check the \`axeOptions\` property (https://www.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,
+        );
+      }
+      win[axeRunningWindowProp] = false;
+
+      const scanMeasure = performance.measure('scan', 'scan-start');
+      const scanDuration = Math.round(scanMeasure.duration);
+
+      if (!enabled.value || !result) {
+        return;
+      }
+
+      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,
+        performance: {
+          totalBlockingTime: scanDuration + domUpdateDuration,
+          scan: scanDuration,
+          domUpdate: domUpdateDuration,
+        },
+      });
+    } catch (error) {
+      win[axeRunningWindowProp] = false;
+      logAndRethrow(error);
+    }
+  }, throttle);
+
+  taskQueue.add(document);
+
+  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' &&
+          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);
+      });
+
+      const nodes = filteredMutationList.map((mutationRecord) => mutationRecord.target);
+      taskQueue.addMultiple(nodes);
+    } catch (error) {
+      logAndRethrow(error);
+    }
+  });
+
+  mutationObserver.observe(document, {
+    subtree: true,
+    childList: true,
+    attributes: true,
+    characterData: true,
+  });
+
+  return () => {
+    mutationObserver.disconnect();
+  };
+}

package/src/scroll-listeners.ts

@@ -0,0 +1,45 @@
+import { effect } from '@preact/signals-core';
+import { logAndRethrow } from './log-and-rethrow.js';
+import { scrollableAncestors } from './state.js';
+import { recalculatePositions } from './utils/recalculate-positions.js';
+
+export 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,35 @@
+import { computed, signal } from '@preact/signals-core';
+
+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,
+    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<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

@@ -0,0 +1,136 @@
+import assert from 'node:assert/strict';
+import { mock, suite, test } from 'node:test';
+
+import { TaskQueue } from './task-queue';
+
+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,61 @@
+import type { Throttle } from './types.ts';
+
+type TaskCallback<T> = (items: Array<T>) => void;
+
+export class TaskQueue<T> {
+  #throttle: Throttle;
+  #asyncCallback: TaskCallback<T> | null = null;
+
+  #items = new Set<T>();
+  #inRunLoop = false;
+
+  constructor(asyncCallback: TaskCallback<T>, 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;
+    }
+
+    const items = Array.from(this.#items);
+
+    this.#items.clear();
+
+    if (this.#asyncCallback) {
+      await this.#asyncCallback(items);
+    }
+
+    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]);
+  }
+}