accented 0.0.0-20250404114312 → 0.0.0-20250618181418

package/src/state.ts

@@ -1,32 +1,35 @@
-import { signal, computed } from '@preact/signals-core';
+import { computed, signal } from '@preact/signals-core';
 
-import type { ElementWithIssues, ExtendedElementWithIssues } from './types';
+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 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 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>()
-  )
+  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

@@ -1,11 +1,12 @@
 import assert from 'node:assert/strict';
-import {mock, suite, test} from 'node:test';
+import { mock, suite, test } from 'node:test';
 
-import TaskQueue from './task-queue.js';
+import { TaskQueue } from './task-queue';
 
-const wait = (duration: number) => new Promise(resolve => setTimeout(resolve, duration));
+const wait = (duration: number) => new Promise((resolve) => setTimeout(resolve, duration));
 
-const createAsyncCallback = (duration: number) => mock.fn(() => 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 () => {

package/src/task-queue.ts

@@ -1,15 +1,15 @@
-import type { Throttle } from './types';
+import type { Throttle } from './types.ts';
 
-type TaskCallback = () => void;
+type TaskCallback<T> = (items: Array<T>) => void;
 
-export default class TaskQueue<T> {
+export class TaskQueue<T> {
   #throttle: Throttle;
-  #asyncCallback: TaskCallback | null = null;
+  #asyncCallback: TaskCallback<T> | null = null;
 
   #items = new Set<T>();
   #inRunLoop = false;
 
-  constructor(asyncCallback: TaskCallback, throttle: Required<Throttle>) {
+  constructor(asyncCallback: TaskCallback<T>, throttle: Required<Throttle>) {
     this.#asyncCallback = asyncCallback;
     this.#throttle = throttle;
   }
@@ -33,10 +33,12 @@ export default class TaskQueue<T> {
       return;
     }
 
+    const items = Array.from(this.#items);
+
     this.#items.clear();
 
     if (this.#asyncCallback) {
-      await this.#asyncCallback();
+      await this.#asyncCallback(items);
     }
 
     await new Promise((resolve) => setTimeout(resolve, this.#throttle.wait));

package/src/types.ts

@@ -1,6 +1,6 @@
-import type axe from 'axe-core';
 import type { Signal } from '@preact/signals-core';
-import type { AccentedTrigger } from './elements/accented-trigger';
+import type axe from 'axe-core';
+import type { AccentedTrigger } from './elements/accented-trigger.ts';
 
 export type Throttle = {
   /**
@@ -8,7 +8,7 @@ export type Throttle = {
    *
    * Default: `1000`.
    * */
-  wait?: number,
+  wait?: number;
 
   /**
    * When to run the scan on Accented initialization or on a mutation.
@@ -17,8 +17,8 @@ export type Throttle = {
    *
    * Default: `true`.
    * */
-  leading?: boolean
-}
+  leading?: boolean;
+};
 
 export type Output = {
   /**
@@ -26,20 +26,44 @@ export type Output = {
    *
    * Default: `true`.
    * */
-  console?: boolean
-}
+  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>;
 
-export type AxeContext = axe.ElementContext;
+// 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]>;
+export type AxeOptions = Pick<axe.RunOptions, (typeof allowedAxeOptions)[number]>;
 
 type CallbackParams = {
   /**
    * The most current array of elements with issues.
    * */
-  elementsWithIssues: Array<ElementWithIssues>,
+  elementsWithIssues: Array<ElementWithIssues>;
 
   /**
    * * `performance`: runtime performance of the last scan. An object:
@@ -47,18 +71,20 @@ type CallbackParams = {
    *   It’s further divided into the `scan` and `domUpdate` phases.
    * * `scan`: how long the `scan` phase took, in milliseconds.
    * * `domUpdate`: how long the `domUpdate` phase took, in milliseconds.
+   * * `scanContext`: nodes that got scanned. Either an array of nodes,
+   *   or an object with `include` and `exclude` properties (if any nodes were excluded).
    * */
   performance: {
-    totalBlockingTime: number,
-    scan: number,
-    domUpdate: number
-  }
-}
+    totalBlockingTime: number;
+    scan: number;
+    domUpdate: number;
+    scanContext: ScanContext | Array<Node>;
+  };
+};
 
 export type Callback = (params: CallbackParams) => void;
 
 export type AccentedOptions = {
-
   /**
    * The `context` parameter for `axe.run()`.
    *
@@ -75,7 +101,7 @@ export type AccentedOptions = {
    *
    * Default: `document`.
    */
-  axeContext?: AxeContext,
+  context?: Context;
 
   /**
    * The `options` parameter for `axe.run()`.
@@ -91,7 +117,7 @@ export type AccentedOptions = {
    *
    * Default: `{}`.
    */
-  axeOptions?: AxeOptions,
+  axeOptions?: AxeOptions;
 
   /**
    * The character sequence that’s used in various elements, attributes and stylesheets that Accented adds to the page.
@@ -108,24 +134,24 @@ export type AccentedOptions = {
    *
    * Default: `accented`.
    */
-  name?: string,
+  name?: string;
 
   /**
    * Output options object.
    * */
-  output?: Output,
+  output?: Output;
 
   /**
    * Scan throttling options object.
    * */
-  throttle?: Throttle,
+  throttle?: Throttle;
 
   /**
    * A callback that will be called after each scan.
    *
    * Default: `() => {}`.
    * */
-  callback?: Callback
+  callback?: Callback;
 };
 
 /**
@@ -135,35 +161,41 @@ export type AccentedOptions = {
 export type DisableAccented = () => void;
 
 export type Position = {
-  left: number,
-  top: number,
-  width: number,
-  height: number
+  left: number;
+  top: number;
+  width: number;
+  height: number;
 };
 
 export type Issue = {
-  id: string,
-  title: string,
-  description: string,
-  url: string,
-  impact: axe.ImpactValue
+  id: string;
+  title: string;
+  description: string;
+  url: string;
+  impact: axe.ImpactValue;
 };
 
 export type BaseElementWithIssues = {
-  element: HTMLElement,
-  rootNode: Node
+  element: HTMLElement | SVGElement;
+  rootNode: Node;
 };
 
-export type ElementWithIssues = BaseElementWithIssues &{
-  issues: Array<Issue>
+export type ElementWithIssues = BaseElementWithIssues & {
+  issues: Array<Issue>;
 };
 
 export type ExtendedElementWithIssues = BaseElementWithIssues & {
-  issues: Signal<ElementWithIssues['issues']>,
-  visible: Signal<boolean>,
-  trigger: AccentedTrigger,
-  position: Signal<Position>,
-  anchorNameValue: string,
-  scrollableAncestors: Signal<Set<Element>>
-  id: number
+  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

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

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

@@ -1,14 +1,14 @@
 import assert from 'node:assert/strict';
-import {suite, test} from 'node:test';
-import areIssueSetsEqual from './are-issue-sets-equal.js';
+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'
+  impact: 'serious',
 };
 
 const issue2: Issue = {
@@ -16,18 +16,22 @@ const issue2: Issue = {
   title: 'title2',
   description: 'description2',
   url: 'http://example.com',
-  impact: 'serious'
+  impact: 'serious',
 };
 
 // @ts-expect-error
-const issue2Clone: Issue = Object.keys(issue2).reduce((obj, key) => { obj[key] = issue2[key]; return obj; }, {});
+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'
+  impact: 'serious',
 };
 
 suite('areIssueSetsEqual', () => {

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

@@ -1,10 +1,12 @@
-import type { Issue } from '../types';
+import type { Issue } from '../types.ts';
 
 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])
-    )));
+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,55 @@
+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')!;
+    console.log(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

@@ -1,7 +1,7 @@
 import assert from 'node:assert/strict';
 import { suite, test } from 'node:test';
 
-import deepMerge from './deep-merge';
+import { deepMerge } from './deep-merge';
 
 suite('deepMerge', () => {
   test('merges two objects with overlapping keys', () => {
@@ -31,4 +31,11 @@ suite('deepMerge', () => {
     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

@@ -1,16 +1,19 @@
+// biome-ignore lint/suspicious/noExplicitAny: I'm not sure how to type this properly
 type AnyObject = Record<string, any>;
 
-export default function deepMerge(target: AnyObject, source: AnyObject): AnyObject {
-  const output = {...target};
+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 (typeof source[key] === 'object' && source[key] !== null && !Array.isArray(source[key])) {
-      if (!(key in target)) {
-        output[key] = source[key];
-      } else {
+    if (isObject(source[key])) {
+      if (isObject(target[key])) {
         output[key] = deepMerge(target[key], source[key]);
+      } else {
+        output[key] = source[key];
       }
-    }
-    else {
+    } else {
       output[key] = source[key];
     }
   }

package/src/utils/dom-helpers.ts

@@ -1,3 +1,16 @@
+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;
 }
@@ -20,3 +33,10 @@ export function isHtmlElement(element: Element): element is HTMLElement {
   // 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

@@ -1,4 +1,4 @@
-export default function getElementHtml(element: Element) {
+export function getElementHtml(element: Element) {
   const outerHtml = element.outerHTML;
   const innerHtml = element.innerHTML;
   if (!innerHtml) {
@@ -9,5 +9,7 @@ export default function getElementHtml(element: Element) {
     // 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);
+  const openingTag = outerHtml.slice(0, index);
+  const closingTag = outerHtml.slice(index + innerHtml.length);
+  return `${openingTag}…${closingTag}`;
 }