accented 0.0.1-dev.4 → 1.0.0

package/src/types.ts

@@ -0,0 +1,258 @@
+import type { Signal } from '@preact/signals-core';
+import type axe from 'axe-core';
+import type { AccentedTrigger } from './elements/accented-trigger.ts';
+
+export type Throttle = {
+  /**
+   * How long Accented must wait (in milliseconds) to run a scan after a mutation or after the previous scan (whichever finished last).
+   *
+   * If the page you’re scanning has a lot of nodes,
+   * scanning may take a noticeable time (~ a few hundred milliseconds),
+   * during which time the main thread will be blocked most of the time.
+   *
+   * You may want to experiment with this value if your page contents change frequently
+   * or if it has JavaScript-based animations running on the main thread.
+   *
+   * @default 1000
+   * */
+  wait?: number;
+
+  /**
+   * If `leading` is set to `true`, the scan runs immediately after a mutation.
+   * In this case, `wait` only applies to subsequent scans,
+   * giving the page at least `wait` milliseconds between the end of the previous scan
+   * and the beginning of the next one.
+   *
+   * If `leading` is set to `false`, the wait applies to mutations as well,
+   * delaying the output.
+   * This may be useful if you’re expecting quick bursts of mutations on your page.
+   *
+   * @default true
+   * */
+  leading?: boolean;
+};
+
+export type Output = {
+  /**
+   * Whether the list of elements with issues should be printed to the browser console whenever issues are added, removed, or changed.
+   *
+   * @default true
+   * */
+  console?: boolean;
+};
+
+/**
+ * Model context type based on axe.ElementContext,
+ * excluding frame selectors (since we don't support scanning iframes).
+ */
+
+export type Selector = Exclude<axe.Selector, axe.LabelledFramesSelector>;
+
+// axe.SelectorList also can have FrameSelector elements in the array.
+// We're not allowing that.
+export type SelectorList = Array<Selector> | NodeList;
+
+// The rest of the type is structured the same as in axe-core.
+export type ContextProp = Selector | SelectorList;
+
+export type ContextObject =
+  | {
+      include: ContextProp;
+      exclude?: ContextProp;
+    }
+  | {
+      exclude: ContextProp;
+      include?: ContextProp;
+    };
+
+export type Context = ContextProp | ContextObject;
+
+export const allowedAxeOptions = ['rules', 'runOnly'] as const;
+
+export type AxeOptions = Pick<axe.RunOptions, (typeof allowedAxeOptions)[number]>;
+
+type CallbackParams = {
+  /**
+   * The most up-to-date array of all elements with accessibility issues.
+   * */
+  elementsWithIssues: Array<ElementWithIssues>;
+
+  /**
+   * Runtime performance of the last scan. An object with the following props:
+   * - `totalBlockingTime`: how long the main thread was blocked by Accented during the last scan, in milliseconds.
+   *   It’s further divided into the `scan` and `domUpdate` phases.
+   * - `scan`: how long scanning (the execution of `axe.run()`) took, in milliseconds.
+   * - `domUpdate`: how long the DOM update (adding / removing outlines and dialog trigger buttons) took, in milliseconds.
+   * */
+  performance: {
+    totalBlockingTime: number;
+    scan: number;
+    domUpdate: number;
+  };
+
+  /**
+   * Nodes that got scanned. Either an array of nodes,
+   * or an object with `include` and `exclude` properties (if any nodes were excluded).
+   */
+  scanContext: ScanContext | Array<Node>;
+};
+
+export type Callback = (params: CallbackParams) => void;
+
+export type AccentedOptions = {
+  /**
+   * 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;
+
+  /**
+   * A function that will be called after each scan.
+   *
+   * Potential uses:
+
+   * - do something with the scan results,
+   * for example send them to a backend for storage and analysis;
+   * - analyze Accented’s performance.
+   *
+   * @default () => {}
+   *
+   * @example
+   *
+   * accented({
+   *   callback: ({ elementsWithIssues, performance, scanContext }) => {
+   *     console.log('Elements with issues:', elementsWithIssues);
+   *     console.log('Total blocking time:', performance.totalBlockingTime);
+   *     console.log('Scan context:', scanContext);
+   *   }
+   * });
+   *
+   * */
+  callback?: Callback;
+
+  /**
+   * The `context` parameter for `axe.run()`.
+   *
+   * Determines what part(s) of the page to scan for accessibility issues.
+   *
+   * Accepts a variety of shapes:
+   *
+   * - a [`Node`](https://developer.mozilla.org/en-US/docs/Web/API/Node) (in practice it will likely be an instance of [`Element`](https://developer.mozilla.org/en-US/docs/Web/API/Element), [`Document`](https://developer.mozilla.org/en-US/docs/Web/API/Document), or [`DocumentFragment`](https://developer.mozilla.org/en-US/docs/Web/API/DocumentFragment));
+   * - a valid [CSS selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_selectors);
+   * - an object for selecting elements within shadow DOM,
+   *   whose shape is `{ fromShadowDom: [selector1, selector2, ...] }`,
+   *   where `selector1`, `selector2`, etc. select shadow hosts, and the last selector selects the actual context.
+   *   `selector2` in this example is _within_ the shadow root created on the element(s) that match `selector1`,
+   *   so in practice you shouldn’t have more than two elements in such an array
+   *   unless you have a very complex structure with multiple shadow DOM layers;
+   * - a [`NodeList`](https://developer.mozilla.org/en-US/docs/Web/API/NodeList) (likely a result of a [`querySelectorAll()`](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelectorAll) call);
+   * - an array containing any combination of selectors, nodes, or shadow DOM objects (described above);
+   * - an object containing `include` and / or `exclude` properties.
+   *   It’s useful if you’d like to exclude certain elements or parts of the page.
+   *   The values for `include` and `exclude` can take any of the above shapes.
+   *   It’s unlikely that you’d want to have complex `include` / `exclude` rules,
+   *   but if you do, the exact behavior is documented by the relevant tests:
+   *   [`is-node-in-scan-context.test.ts`](https://github.com/pomerantsev/accented/blob/main/packages/accented/src/utils/is-node-in-scan-context.test.ts).
+   *
+   * See also the documentation for the [`context` parameter of `axe.run()`](https://www.deque.com/axe/core-documentation/api-documentation/#context-parameter),
+   * which the `context` option from Accented mostly mirrors
+   * (note that Accented doesn’t support the `fromFrames` object shape).
+   *
+   * @default document
+   */
+  context?: Context;
+
+  /**
+   * The character sequence that’s used in various elements, attributes and stylesheets that Accented adds to the page.
+   *
+   * You shouldn’t have to provide this prop unless some of the names on your page have "accented" in it and conflict with what Accented provides by default.
+   *
+   * * The data attribute that’s added to elements with issues (default: `data-accented`).
+   * * The names of 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'
+   *
+   * @example
+   *
+   * accented({name: 'my-name'});
+   *
+   * With the above option provided, the attribute set on elements with issues will be `data-my-name`,
+   * a custom element will be called `my-name-trigger`, and so on.
+   *
+   */
+  name?: string;
+
+  /**
+   * An object controlling how the results of scans are presented.
+   * */
+  output?: Output;
+
+  /**
+   * An object controlling at what moments Accented will run its scans.
+   * */
+  throttle?: Throttle;
+};
+
+/**
+ * A function that fully disables Accented,
+ * stopping the scanning and removing all highlights from the page.
+ */
+export type DisableAccented = () => void;
+
+export type Position = {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+};
+
+export type Issue = {
+  id: string;
+  title: string;
+  description: string;
+  url: string;
+  impact: axe.ImpactValue;
+};
+
+export type BaseElementWithIssues = {
+  element: HTMLElement | SVGElement;
+  rootNode: Node;
+};
+
+export type ElementWithIssues = BaseElementWithIssues & {
+  issues: Array<Issue>;
+};
+
+export type ExtendedElementWithIssues = BaseElementWithIssues & {
+  issues: Signal<ElementWithIssues['issues']>;
+  visible: Signal<boolean>;
+  trigger: AccentedTrigger;
+  position: Signal<Position>;
+  skipRender: boolean;
+  anchorNameValue: string;
+  scrollableAncestors: Signal<Set<Element>>;
+  id: number;
+};
+
+export type ScanContext = {
+  include: Array<Node>;
+  exclude: Array<Node>;
+};

package/src/utils/are-elements-with-issues-equal.ts

@@ -0,0 +1,11 @@
+import type { BaseElementWithIssues } from '../types.ts';
+
+export function areElementsWithIssuesEqual(
+  elementWithIssues1: BaseElementWithIssues,
+  elementWithIssues2: BaseElementWithIssues,
+) {
+  return (
+    elementWithIssues1.element === elementWithIssues2.element &&
+    elementWithIssues1.rootNode === elementWithIssues2.rootNode
+  );
+}

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

@@ -0,0 +1,53 @@
+import assert from 'node:assert/strict';
+import { suite, test } from 'node:test';
+import type { Issue } from '../types';
+import { areIssueSetsEqual } from './are-issue-sets-equal';
+
+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) => {
+  // @ts-expect-error
+  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,12 @@
+import type { Issue } from '../types.ts';
+
+const issueProps: Array<keyof Issue> = ['id', 'title', 'description', 'url', 'impact'];
+
+export 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/containing-blocks.ts

@@ -0,0 +1,60 @@
+/**
+ * Tests whether a particular combination of CSS property and value on an element
+ * makes that element a containing block.
+ * https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_display/Containing_block
+ *
+ * The function is meant to be run with properties that behave inconsistently across browsers.
+ *
+ * It's only meant to be used during initialization.
+ */
+function testContainingBlockCreation<T extends keyof CSSStyleDeclaration>(
+  prop: T,
+  value: CSSStyleDeclaration[T],
+) {
+  const container = document.createElement('div');
+  container.style[prop] = value;
+  container.style.position = 'fixed';
+  container.style.insetInlineStart = '10px';
+  container.style.insetBlockStart = '10px';
+
+  const element = document.createElement('div');
+  element.style.position = 'fixed';
+  element.style.insetInlineStart = '0';
+  element.style.insetBlockStart = '0';
+
+  container.appendChild(element);
+  document.body.appendChild(container);
+  const containerRect = container.getBoundingClientRect();
+  const elementRect = element.getBoundingClientRect();
+
+  container.remove();
+
+  return containerRect.top === elementRect.top && containerRect.left === elementRect.left;
+}
+
+// This is the set we'll use to store the properties that _may_ create containing blocks
+// (the behavior of the ones that we'll be checking is inconsistent across browsers
+// at the time of writing this comment).
+const propsAffectingContainingBlocks = new Set<keyof CSSStyleDeclaration>();
+
+export function createsContainingBlock(prop: keyof CSSStyleDeclaration) {
+  return propsAffectingContainingBlocks.has(prop);
+}
+
+export function initializeContainingBlockSupportSet() {
+  type StyleEntry<T extends keyof CSSStyleDeclaration> = {
+    [K in T]: { prop: K; value: CSSStyleDeclaration[K] };
+  }[T];
+
+  const propsToTest: Array<StyleEntry<'filter' | 'backdropFilter' | 'containerType'>> = [
+    { prop: 'filter', value: 'blur(1px)' },
+    { prop: 'backdropFilter', value: 'blur(1px)' },
+    { prop: 'containerType', value: 'size' },
+  ];
+
+  for (const { prop, value } of propsToTest) {
+    if (testContainingBlockCreation(prop, value)) {
+      propsAffectingContainingBlocks.add(prop);
+    }
+  }
+}

package/src/utils/contains.test.ts

@@ -0,0 +1,54 @@
+import assert from 'node:assert/strict';
+import { suite, test } from 'node:test';
+import { JSDOM } from 'jsdom';
+import { contains } from './contains';
+
+suite('contains', () => {
+  test('an element contains itself', () => {
+    const dom = new JSDOM('<div id="test"></div>');
+    const { document } = dom.window;
+    const element = document.querySelector('#test')!;
+
+    assert.equal(contains(element, element), true);
+  });
+
+  test('an element does not contain its sibling', () => {
+    const dom = new JSDOM('<div><div id="sibling1"></div><div id="sibling2"></div></div>');
+    const { document } = dom.window;
+    const sibling1 = document.querySelector('#sibling1')!;
+    const sibling2 = document.querySelector('#sibling2')!;
+
+    assert.equal(contains(sibling1, sibling2), false);
+  });
+
+  test('an element contain its descendant', () => {
+    const dom = new JSDOM('<div id="ancestor"><div id="descendant"></div></div>');
+    const { document } = dom.window;
+    const ancestor = document.querySelector('#ancestor')!;
+    const descendant = document.querySelector('#descendant')!;
+
+    assert.equal(contains(ancestor, descendant), true);
+  });
+
+  test('an element contain its descendant', () => {
+    const dom = new JSDOM('<div id="ancestor"><div id="descendant"></div></div>');
+    const { document } = dom.window;
+    const ancestor = document.querySelector('#ancestor')!;
+    const descendant = document.querySelector('#descendant')!;
+
+    assert.equal(contains(descendant, ancestor), false);
+  });
+
+  test('an element contain its descendant if the descendant is in a shadow DOM', () => {
+    const dom = new JSDOM('<div id="ancestor"><div id="host"></div></div>');
+    global.Node = dom.window.Node;
+    const { document } = dom.window;
+    const ancestor = document.querySelector('#ancestor')!;
+    const host = document.querySelector('#host')!;
+    const shadowRoot = host.attachShadow({ mode: 'open' });
+    shadowRoot.innerHTML = '<div id="descendant"></div>';
+    const descendant = shadowRoot.querySelector('#descendant')!;
+
+    assert.equal(contains(ancestor, descendant), true);
+  });
+});

package/src/utils/contains.ts

@@ -0,0 +1,19 @@
+import { isDocumentFragment, isShadowRoot } from './dom-helpers.js';
+
+export function contains(ancestor: Node, descendant: Node): boolean {
+  if (ancestor.contains(descendant)) {
+    return true;
+  }
+  let rootNode = descendant.getRootNode();
+  while (rootNode) {
+    if (!(isDocumentFragment(rootNode) && isShadowRoot(rootNode))) {
+      return false;
+    }
+    const host = rootNode.host;
+    if (ancestor.contains(host)) {
+      return true;
+    }
+    rootNode = host.getRootNode();
+  }
+  return false;
+}

package/src/utils/deduplicate-nodes.ts

@@ -0,0 +1,3 @@
+export function deduplicateNodes(nodes: Array<Node>): Array<Node> {
+  return [...new Set(nodes)];
+}

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

@@ -0,0 +1,41 @@
+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 });
+  });
+
+  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] });
+  });
+
+  test('handles merging an object into a string in a logical way', () => {
+    const target = { a: 'hello' };
+    const source = { a: { b: 'bye' } };
+    const result = deepMerge(target, source);
+    assert.deepEqual(result, { a: { b: 'bye' } });
+  });
+});

package/src/utils/deep-merge.ts

@@ -0,0 +1,24 @@
+import { isNode } from './dom-helpers.js';
+
+// biome-ignore lint/suspicious/noExplicitAny: I'm not sure how to type this properly
+type AnyObject = Record<string, any>;
+
+const isObject = (obj: unknown): obj is AnyObject =>
+  typeof obj === 'object' && obj !== null && !Array.isArray(obj);
+
+export function deepMerge(target: AnyObject, source: AnyObject): AnyObject {
+  const output = { ...target };
+  for (const key of Object.keys(source)) {
+    if (isObject(source[key])) {
+      // Don't merge DOM nodes.
+      if (isObject(target[key]) && !isNode(target[key])) {
+        output[key] = deepMerge(target[key], source[key]);
+      } else {
+        output[key] = source[key];
+      }
+    } else {
+      output[key] = source[key];
+    }
+  }
+  return output;
+}

package/src/utils/dom-helpers.ts

@@ -0,0 +1,42 @@
+export function isNode(obj: object): obj is Node {
+  return (
+    'nodeType' in obj &&
+    typeof obj.nodeType === 'number' &&
+    'nodeName' in obj &&
+    typeof obj.nodeName === 'string'
+  );
+}
+
+export function isNodeList(obj: object): obj is NodeList {
+  return Object.prototype.toString.call(obj) === '[object NodeList]';
+}
+
+export function isElement(node: Node): node is Element {
+  return typeof Node !== 'undefined' && node.nodeType === Node.ELEMENT_NODE;
+}
+
+export function isDocument(node: Node): node is Document {
+  return typeof Node !== 'undefined' && node.nodeType === Node.DOCUMENT_NODE;
+}
+
+export function isDocumentFragment(node: Node): node is DocumentFragment {
+  return typeof Node !== 'undefined' && node.nodeType === Node.DOCUMENT_FRAGMENT_NODE;
+}
+
+export function isShadowRoot(documentFragment: DocumentFragment): documentFragment is ShadowRoot {
+  return 'host' in documentFragment;
+}
+
+export function isHtmlElement(element: Element): element is HTMLElement {
+  // We can't use instanceof because it may not work across contexts
+  // (such as when an element is moved from an iframe).
+  // This heuristic seems to be the most robust and fastest that I could think of.
+  return element.constructor.name.startsWith('HTML');
+}
+
+export function isSvgElement(element: Element): element is SVGElement {
+  // We can't use instanceof because it may not work across contexts
+  // (such as when an element is moved from an iframe).
+  // This heuristic seems to be the most robust and fastest that I could think of.
+  return element.constructor.name.startsWith('SVG');
+}

package/src/utils/ensure-non-empty.ts

@@ -0,0 +1,6 @@
+export function ensureNonEmpty<T>(arr: T[]): [T, ...T[]] {
+  if (arr.length === 0) {
+    throw new Error('Array must not be empty');
+  }
+  return arr as [T, ...T[]];
+}

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

@@ -0,0 +1,15 @@
+export 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;
+  }
+  const openingTag = outerHtml.slice(0, index);
+  const closingTag = outerHtml.slice(index + innerHtml.length);
+  return `${openingTag}…${closingTag}`;
+}