accented 0.0.0-20250124142030

package/src/utils/transform-violations.test.ts

@@ -0,0 +1,124 @@
+import assert from 'node:assert/strict';
+import {suite, test} from 'node:test';
+import transformViolations from './transform-violations';
+
+import type { AxeResults } from 'axe-core';
+type Violation = AxeResults['violations'][number];
+type Node = Violation['nodes'][number];
+
+const commonViolationProps1: Omit<Violation, 'nodes'> = {
+  id: 'id1',
+  help: 'help1',
+  helpUrl: 'http://example.com',
+  description: 'description1',
+  tags: [],
+  impact: 'serious'
+};
+
+const commonViolationProps2: Omit<Violation, 'nodes'> = {
+  id: 'id2',
+  help: 'help2',
+  helpUrl: 'http://example.com',
+  description: 'description2',
+  tags: [],
+  impact: 'serious'
+};
+
+// @ts-expect-error element is not HTMLElement
+const element1: HTMLElement = {};
+// @ts-expect-error element is not HTMLElement
+const element2: HTMLElement = {};
+// @ts-expect-error element is not HTMLElement
+const element3: HTMLElement = {};
+
+const commonNodeProps = {
+  html: '<div></div>',
+  any: [],
+  all: [],
+  none: []
+};
+
+const node1: Node = {
+  ...commonNodeProps,
+  element: element1,
+  target: ['div'],
+  failureSummary: 'summary1'
+};
+
+const node2: Node = {
+  ...commonNodeProps,
+  element: element2,
+  target: ['div'],
+  failureSummary: 'summary2'
+};
+
+const node3: Node = {
+  ...commonNodeProps,
+  element: element3,
+  target: ['div'],
+  failureSummary: 'summary3'
+};
+
+suite('transformViolations', () => {
+  test('one violation, one element', () => {
+    const violation: Violation = {
+      ...commonViolationProps1,
+      nodes: [node1]
+    };
+    const elementsWithIssues = transformViolations([violation]);
+    assert.equal(elementsWithIssues.length, 1);
+    assert.equal(elementsWithIssues[0]?.element, element1);
+    assert.equal(elementsWithIssues[0].issues.length, 1);
+    assert.equal(elementsWithIssues[0].issues[0]?.id, 'id1');
+    assert.equal(elementsWithIssues[0].issues[0]?.description, 'summary1');
+  });
+
+  test('two violations, two elements each', () => {
+    const violation1: Violation = {
+      ...commonViolationProps1,
+      nodes: [node1, node2]
+    };
+    const violation2: Violation = {
+      ...commonViolationProps2,
+      nodes: [node1, node3]
+    };
+    const elementsWithIssues = transformViolations([violation1, violation2]);
+    assert.equal(elementsWithIssues.length, 3);
+    const elementWithTwoIssues = elementsWithIssues.find(elementWithIssues => elementWithIssues.element === element1);
+    assert.equal(elementWithTwoIssues?.issues.length, 2);
+  });
+
+  test('a violation in an iframe', () => {
+    const node: Node = {
+      ...commonNodeProps,
+      element: element1,
+      // A target array whose length is > 1 signifies an element in an iframe
+      target: ['iframe', 'div'],
+      failureSummary: 'summary1'
+    };
+    const violation: Violation = {
+      ...commonViolationProps1,
+      nodes: [node]
+    };
+
+    const elementsWithIssues = transformViolations([violation]);
+    assert.equal(elementsWithIssues.length, 0);
+  });
+
+  test('a violation in shadow DOM', () => {
+    const node: Node = {
+      ...commonNodeProps,
+      element: element1,
+      // A target that contains an array within the outer array signifies an element in shadow DOM
+      target: [['div', 'div']],
+      failureSummary: 'summary1'
+    };
+    const violation: Violation = {
+      ...commonViolationProps1,
+      nodes: [node]
+    };
+
+    const elementsWithIssues = transformViolations([violation]);
+    assert.equal(elementsWithIssues.length, 0);
+  });
+});

package/src/utils/transform-violations.ts

@@ -0,0 +1,45 @@
+import type { AxeResults } from 'axe-core';
+import type { Issue, ElementWithIssues } from '../types';
+
+export default function transformViolations(violations: typeof AxeResults.violations) {
+  const elementsWithIssues: Array<ElementWithIssues> = [];
+
+  for (const violation of violations) {
+    for (const node of violation.nodes) {
+      const { element, target } = node;
+
+      // 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.
+      const isInIframe = target.length > 1;
+
+      // Highlighting elements in shadow DOM is not yet supported, see https://github.com/pomerantsev/accented/issues/25
+      // Until then, we don’t want such elements to be added to the set.
+      const isInShadowDOM = Array.isArray(target[0]);
+
+      if (element && !isInIframe && !isInShadowDOM) {
+        const issue: Issue = {
+          id: violation.id,
+          title: violation.help,
+          description: node.failureSummary ?? violation.description,
+          url: violation.helpUrl,
+          impact: violation.impact ?? null
+        };
+        const existingElementIndex = elementsWithIssues.findIndex(elementWithIssues => elementWithIssues.element === element);
+        if (existingElementIndex === -1) {
+          elementsWithIssues.push({
+            element,
+            issues: [issue]
+          });
+        } else {
+          elementsWithIssues[existingElementIndex]!.issues.push(issue);
+        }
+      }
+    }
+  }
+
+  return elementsWithIssues;
+}

package/src/utils/update-elements-with-issues.test.ts

@@ -0,0 +1,209 @@
+import {suite, test} from 'node:test';
+import assert from 'node:assert/strict';
+import type { Signal } from '@preact/signals-core';
+import { signal } from '@preact/signals-core';
+import type { ExtendedElementWithIssues, Issue } from '../types';
+import updateElementsWithIssues from './update-elements-with-issues';
+
+import type { AxeResults, ImpactValue } from 'axe-core';
+import type { AccentedContainer } from '../elements/accented-container';
+type Violation = AxeResults['violations'][number];
+type Node = Violation['nodes'][number];
+
+const win: Window = {
+  document: {
+    // @ts-expect-error the return value is of incorrect type.
+    createElement: () => ({
+      style: {
+        setProperty: () => {}
+      },
+      dataset: {}
+    })
+  },
+  // @ts-expect-error we're missing a lot of properties
+  getComputedStyle: () => ({
+    zIndex: ''
+  })
+}
+
+// @ts-expect-error element is not HTMLElement
+const element1: HTMLElement = {};
+// @ts-expect-error element is not HTMLElement
+const element2: HTMLElement = {};
+
+const accentedContainer = win.document.createElement('accented-container') as AccentedContainer;
+
+const commonNodeProps = {
+  html: '<div></div>',
+  any: [],
+  all: [],
+  none: [],
+  target: ['div']
+};
+
+const node1: Node = {
+  ...commonNodeProps,
+  element: element1,
+};
+
+const node2: Node = {
+  ...commonNodeProps,
+  element: element2,
+};
+
+const commonViolationProps = {
+  help: 'help',
+  helpUrl: 'http://example.com',
+  description: 'description',
+  tags: [],
+  impact: 'serious' as ImpactValue
+};
+
+const violation1: Violation = {
+  ...commonViolationProps,
+  id: 'id1',
+  nodes: [node1]
+};
+
+const violation2: Violation = {
+  ...commonViolationProps,
+  id: 'id2',
+  nodes: [node2]
+};
+
+const violation3: Violation = {
+  ...commonViolationProps,
+  id: 'id3',
+  nodes: [node2]
+};
+
+const commonIssueProps = {
+  title: 'help',
+  description: 'description',
+  url: 'http://example.com',
+  impact: 'serious'
+} as const;
+
+const issue1: Issue = {
+  id: 'id1',
+  ...commonIssueProps
+};
+
+const issue2: Issue = {
+  id: 'id2',
+  ...commonIssueProps
+};
+
+const issue3: Issue = {
+  id: 'id3',
+  ...commonIssueProps
+};
+
+suite('updateElementsWithIssues', () => {
+  test('no changes', () => {
+    const extendedElementsWithIssues: Signal<Array<ExtendedElementWithIssues>> = signal([
+      {
+        id: 1,
+        element: element1,
+        accentedContainer,
+        issues: signal([issue1])
+      },
+      {
+        id: 2,
+        element: element2,
+        accentedContainer,
+        issues: signal([issue2])
+      }
+    ]);
+    updateElementsWithIssues(extendedElementsWithIssues, [violation1, violation2], win, 'accented');
+    assert.equal(extendedElementsWithIssues.value.length, 2);
+    assert.equal(extendedElementsWithIssues.value[0]?.element, element1);
+    assert.equal(extendedElementsWithIssues.value[0]?.issues.value.length, 1);
+    assert.equal(extendedElementsWithIssues.value[1]?.element, element2);
+    assert.equal(extendedElementsWithIssues.value[1]?.issues.value.length, 1);
+  });
+
+  test('one issue added', () => {
+    const extendedElementsWithIssues: Signal<Array<ExtendedElementWithIssues>> = signal([
+      {
+        id: 1,
+        element: element1,
+        accentedContainer,
+        issues: signal([issue1])
+      },
+      {
+        id: 2,
+        element: element2,
+        accentedContainer,
+        issues: signal([issue2])
+      }
+    ]);
+    updateElementsWithIssues(extendedElementsWithIssues, [violation1, violation2, violation3], win, 'accented');
+    assert.equal(extendedElementsWithIssues.value.length, 2);
+    assert.equal(extendedElementsWithIssues.value[0]?.element, element1);
+    assert.equal(extendedElementsWithIssues.value[0]?.issues.value.length, 1);
+    assert.equal(extendedElementsWithIssues.value[1]?.element, element2);
+    assert.equal(extendedElementsWithIssues.value[1]?.issues.value.length, 2);
+  });
+
+  test('one issue removed', () => {
+    const extendedElementsWithIssues: Signal<Array<ExtendedElementWithIssues>> = signal([
+      {
+        id: 1,
+        element: element1,
+        accentedContainer,
+        issues: signal([issue1])
+      },
+      {
+        id: 2,
+        element: element2,
+        accentedContainer,
+        issues: signal([issue2, issue3])
+      }
+    ]);
+    updateElementsWithIssues(extendedElementsWithIssues, [violation1, violation2], win, 'accented');
+    assert.equal(extendedElementsWithIssues.value.length, 2);
+    assert.equal(extendedElementsWithIssues.value[0]?.element, element1);
+    assert.equal(extendedElementsWithIssues.value[0]?.issues.value.length, 1);
+    assert.equal(extendedElementsWithIssues.value[1]?.element, element2);
+    assert.equal(extendedElementsWithIssues.value[1]?.issues.value.length, 1);
+  });
+
+  test('one element added', () => {
+    const extendedElementsWithIssues: Signal<Array<ExtendedElementWithIssues>> = signal([
+      {
+        id: 1,
+        element: element1,
+        accentedContainer,
+        issues: signal([issue1])
+      }
+    ]);
+    updateElementsWithIssues(extendedElementsWithIssues, [violation1, violation2], win, 'accented');
+    assert.equal(extendedElementsWithIssues.value.length, 2);
+    assert.equal(extendedElementsWithIssues.value[0]?.element, element1);
+    assert.equal(extendedElementsWithIssues.value[0]?.issues.value.length, 1);
+    assert.equal(extendedElementsWithIssues.value[1]?.element, element2);
+    assert.equal(extendedElementsWithIssues.value[1]?.issues.value.length, 1);
+  });
+
+  test('one element removed', () => {
+    const extendedElementsWithIssues: Signal<Array<ExtendedElementWithIssues>> = signal([
+      {
+        id: 1,
+        element: element1,
+        accentedContainer,
+        issues: signal([issue1])
+      },
+      {
+        id: 2,
+        element: element2,
+        accentedContainer,
+        issues: signal([issue2])
+      }
+    ]);
+    updateElementsWithIssues(extendedElementsWithIssues, [violation1], win, 'accented');
+    assert.equal(extendedElementsWithIssues.value.length, 1);
+    assert.equal(extendedElementsWithIssues.value[0]?.element, element1);
+    assert.equal(extendedElementsWithIssues.value[0]?.issues.value.length, 1);
+  });
+});

package/src/utils/update-elements-with-issues.ts

@@ -0,0 +1,55 @@
+import type { AxeResults } from 'axe-core';
+import type { Signal } from '@preact/signals-core';
+import { batch, signal } from '@preact/signals-core';
+import type { ExtendedElementWithIssues } from '../types';
+import transformViolations from './transform-violations.js';
+import areIssueSetsEqual from './are-issue-sets-equal.js';
+import type { AccentedContainer } from '../elements/accented-container';
+
+let count = 0;
+
+export default function updateElementsWithIssues(extendedElementsWithIssues: Signal<Array<ExtendedElementWithIssues>>, violations: typeof AxeResults.violations, win: Window, name: string) {
+  const updatedElementsWithIssues = transformViolations(violations);
+
+  batch(() => {
+    for (const updatedElementWithIssues of updatedElementsWithIssues) {
+      const existingElementIndex = extendedElementsWithIssues.value.findIndex(extendedElementWithIssues => extendedElementWithIssues.element === updatedElementWithIssues.element);
+      if (existingElementIndex > -1 && extendedElementsWithIssues.value[existingElementIndex] && !areIssueSetsEqual(extendedElementsWithIssues.value[existingElementIndex].issues.value, updatedElementWithIssues.issues)) {
+        extendedElementsWithIssues.value[existingElementIndex].issues.value = updatedElementWithIssues.issues;
+      }
+    }
+
+    const addedElementsWithIssues = updatedElementsWithIssues.filter(updatedElementWithIssues => {
+      return !extendedElementsWithIssues.value.some(extendedElementWithIssues => extendedElementWithIssues.element === updatedElementWithIssues.element);
+    });
+
+    const removedElementsWithIssues = extendedElementsWithIssues.value.filter(extendedElementWithIssues => {
+      return !updatedElementsWithIssues.some(updatedElementWithIssues => updatedElementWithIssues.element === extendedElementWithIssues.element);
+    });
+
+    if (addedElementsWithIssues.length > 0 || removedElementsWithIssues.length > 0) {
+      extendedElementsWithIssues.value = [...extendedElementsWithIssues.value]
+        .filter(extendedElementWithIssues => {
+          return !removedElementsWithIssues.some(removedElementWithIssues => removedElementWithIssues.element === extendedElementWithIssues.element);
+        })
+        .concat(addedElementsWithIssues.map(addedElementWithIssues => {
+          const id = count++;
+          const accentedContainer = win.document.createElement(`${name}-container`) as AccentedContainer;
+          const elementZIndex = parseInt(win.getComputedStyle(addedElementWithIssues.element).zIndex, 10);
+          if (!isNaN(elementZIndex)) {
+            accentedContainer.style.setProperty('z-index', (elementZIndex + 1).toString());
+          }
+          accentedContainer.style.setProperty('position-anchor', `--${name}-anchor-${id}`);
+          accentedContainer.dataset.id = id.toString();
+          const issues = signal(addedElementWithIssues.issues);
+          accentedContainer.issues = issues;
+          return {
+            id,
+            element: addedElementWithIssues.element,
+            accentedContainer,
+            issues
+          };
+        }));
+    }
+  });
+}