accented 0.0.0-20250124142030

package/src/elements/accented-container.ts

@@ -0,0 +1,147 @@
+import type { Issue } from '../types';
+import type { Signal } from '@preact/signals-core';
+import { effect } from '@preact/signals-core';
+
+export interface AccentedContainer extends HTMLElement {
+  issues: Signal<Array<Issue>> | undefined;
+}
+
+// We want Accented to not throw an error in Node, and use static imports,
+// so we can't export `class extends HTMLElement` because HTMLElement is not available in Node.
+export default (name: string) => {
+  const containerTemplate = document.createElement('template');
+  containerTemplate.innerHTML = `
+    <button id="trigger">⚠</button>
+    <dialog dir="ltr" aria-labelledby="title">
+      <h2 id="title">Issues</h2>
+      <ul id="issues"></ul>
+    </dialog>
+  `;
+
+  const issueTemplate = document.createElement('template');
+  issueTemplate.innerHTML = `
+    <li>
+      <a></a>
+      <div></div>
+    </li>
+  `;
+
+  const descriptionTemplate = document.createElement('template');
+  descriptionTemplate.innerHTML = `
+    <span></span>
+    <ul></ul>
+  `;
+
+  const stylesheet = new CSSStyleSheet();
+  stylesheet.replaceSync(`
+    :host {
+      position: absolute;
+      inset-inline-end: anchor(end);
+      inset-block-end: anchor(end);
+
+      /* Popover-specific stuff */
+      border: none;
+      padding: 0;
+      margin-inline-end: 0;
+      margin-block-end: 0;
+    }
+
+    #trigger {
+      box-sizing: border-box;
+      font-size: 1rem;
+      inline-size: max(32px, 2rem);
+      block-size: max(32px, 2rem);
+
+      /* Make it look better in forced-colors mode, */
+      border: 2px solid transparent;
+
+      background-color: var(--${name}-primary-color);
+      color: var(--${name}-secondary-color);
+
+      outline-offset: -4px;
+      outline-color: var(--${name}-secondary-color);
+
+      &:focus-visible {
+        outline-width: 2px;
+        outline-style: solid;
+      }
+
+      &:hover:not(:focus-visible) {
+        outline-width: 2px;
+        outline-style: dashed;
+      }
+    }
+  `);
+
+  return class AccentedContainerLocal extends HTMLElement implements AccentedContainer {
+    #abortController: AbortController | undefined;
+
+    #disposeOfEffect: (() => void) | undefined;
+
+    issues: Signal<Array<Issue>> | undefined;
+
+    constructor() {
+      super();
+      this.attachShadow({ mode: 'open' });
+      const content = containerTemplate.content.cloneNode(true);
+      if (this.shadowRoot) {
+        this.shadowRoot.adoptedStyleSheets.push(stylesheet);
+        this.shadowRoot.append(content);
+      }
+    }
+
+    connectedCallback() {
+      if (this.shadowRoot) {
+        const { shadowRoot } = this;
+        const trigger = shadowRoot.getElementById('trigger');
+        const dialog = shadowRoot.querySelector('dialog');
+        this.#abortController = new AbortController();
+        trigger?.addEventListener('click', () => {
+          dialog?.showModal();
+        }, { signal: this.#abortController.signal });
+
+        this.#disposeOfEffect = effect(() => {
+          if (this.issues) {
+            const issues = this.issues.value;
+            const issuesList = shadowRoot.getElementById('issues');
+            if (issuesList) {
+              issuesList.innerHTML = '';
+              for (const issue of issues) {
+                const issueContent = issueTemplate.content.cloneNode(true) as Element;
+                const a = issueContent.querySelector('a');
+                const div = issueContent.querySelector('div');
+                if (a && div) {
+                  a.textContent = issue.title;
+                  a.href = issue.url;
+                  const descriptionItems = issue.description.split(/\n\s*/);
+                  const descriptionContent = descriptionTemplate.content.cloneNode(true) as Element;
+                  const descriptionTitle = descriptionContent.querySelector('span');
+                  const descriptionList = descriptionContent.querySelector('ul');
+                  if (descriptionTitle && descriptionList && descriptionItems.length > 1) {
+                    descriptionTitle.textContent = descriptionItems[0]!;
+                    for (const descriptionItem of descriptionItems.slice(1)) {
+                      const li = document.createElement('li');
+                      li.textContent = descriptionItem;
+                      descriptionList.appendChild(li);
+                    }
+                    div.appendChild(descriptionContent);
+                  }
+                }
+                issuesList.appendChild(issueContent);
+              }
+            }
+          }
+        });
+      }
+    }
+
+    disconnectedCallback() {
+      if (this.#abortController) {
+        this.#abortController.abort();
+      }
+      if (this.#disposeOfEffect) {
+        this.#disposeOfEffect();
+      }
+    }
+  };
+};

package/src/logger.ts

@@ -0,0 +1,21 @@
+import { effect } from '@preact/signals-core';
+import { elementsWithIssues } from './state.js';
+
+const accentedUrl = 'https://www.npmjs.com/package/accented';
+
+export default function createLogger() {
+
+  let firstRun = true;
+
+  return effect(() => {
+    if (elementsWithIssues.value.length > 0) {
+      console.log(`Elements with accessibility issues, identified by Accented (${accentedUrl}):\n`, elementsWithIssues.value);
+    } else {
+      if (firstRun) {
+        firstRun = false;
+      } else {
+        console.log(`No elements with accessibility issues identified by Accented (${accentedUrl}).`);
+      }
+    }
+  });
+}

package/src/scanner.ts

@@ -0,0 +1,68 @@
+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 updateElementsWithIssues from './utils/update-elements-with-issues.js';
+
+export default function createScanner(name: string, throttle: Required<Throttle>, callback: Callback) {
+  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) {
+      return;
+    }
+
+    updateElementsWithIssues(extendedElementsWithIssues, result.violations, window, name);
+
+    callback({
+      elementsWithIssues: elementsWithIssues.value,
+      scanDuration: Math.round(axeMeasure.duration)
+    });
+  }, throttle);
+
+  taskQueue.add(document);
+
+  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);
+      }
+      return nodes;
+    }, new Set<Node>());
+
+    const filteredMutationList = listWithoutAccentedContainers.filter(mutationRecord => {
+      return !elementsWithAccentedAttributeChanges.has(mutationRecord.target);
+    });
+
+    taskQueue.addMultiple(filteredMutationList.map(mutationRecord => mutationRecord.target));
+  });
+
+  mutationObserver.observe(document, {
+    subtree: true,
+    childList: true,
+    attributes: true,
+    characterData: true
+  });
+
+  return () => {
+    mutationObserver.disconnect();
+  };
+}

package/src/state.ts

@@ -0,0 +1,12 @@
+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
+})));

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,97 @@
+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;
+
+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
+}
+
+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 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-").
+   *
+   * Default: "accented".
+   */
+  name?: string,
+
+  /**
+   * Whether to output the issues to the console.
+   *
+   * Default: true.
+   * */
+  outputToConsole?: boolean,
+
+  /**
+   * 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 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']>,
+  accentedContainer: AccentedContainer,
+  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])
+    )));
+}

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

@@ -0,0 +1,27 @@
+import assert from 'node:assert/strict';
+import { suite, test } from 'node:test';
+
+import deepMerge from './deep-merge';
+
+suite('deepMerge', () => {
+  test('merges two objects with overlapping keys', () => {
+    const target = { a: 1, b: 2 };
+    const source = { b: 3, c: 4 };
+    const result = deepMerge(target, source);
+    assert.deepEqual(result, { a: 1, b: 3, c: 4 });
+  });
+
+  test('deeply merges nested objects', () => {
+    const target = { a: 1, b: { x: 1, y: 2 } };
+    const source = { b: { y: 3, z: 4 }, c: 5 };
+    const result = deepMerge(target, source);
+    assert.deepEqual(result, { a: 1, b: { x: 1, y: 3, z: 4 }, c: 5 });
+  });
+
+  test('handles null values in a logical way', () => {
+    const target = { a: 1 };
+    const source = { a: null };
+    const result = deepMerge(target, source);
+    assert.deepEqual(result, { a: null });
+  });
+});

package/src/utils/deep-merge.ts

@@ -0,0 +1,18 @@
+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 (!(key in target)) {
+        output[key] = source[key];
+      } else {
+        output[key] = deepMerge(target[key], source[key]);
+      }
+    }
+    else {
+      output[key] = source[key];
+    }
+  }
+  return output;
+}