accented 0.0.1-dev.4 → 1.0.0

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

@@ -0,0 +1,128 @@
+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',
+};
+
+const getRootNode = (): Node => ({}) as Node;
+
+// @ts-expect-error element is not HTMLElement
+const element1: HTMLElement = { getRootNode };
+// @ts-expect-error element is not HTMLElement
+const element2: HTMLElement = { getRootNode };
+// @ts-expect-error element is not HTMLElement
+const element3: HTMLElement = { getRootNode };
+
+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], 'accented');
+    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], 'accented');
+    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], 'accented');
+    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], 'accented');
+    assert.equal(elementsWithIssues.length, 1);
+  });
+});

package/src/utils/transform-violations.ts

@@ -0,0 +1,74 @@
+import type { AxeResults, ImpactValue } from 'axe-core';
+import type { ElementWithIssues, Issue } from '../types.ts';
+
+// This is a list of axe-core violations (their ids) that may be flagged by axe-core
+// as false positives if an Accented trigger is a descendant of the element with the issue.
+const violationsAffectedByAccentedTriggers = [
+  'aria-hidden-focus',
+  'aria-text',
+  'definition-list',
+  'label-content-name-mismatch',
+  'list',
+  'nested-interactive',
+  'scrollable-region-focusable', // The Accented trigger might make the content grow such that scrolling is required.
+];
+
+function maybeCausedByAccented(violationId: string, element: HTMLElement, name: string) {
+  return (
+    violationsAffectedByAccentedTriggers.includes(violationId) &&
+    Boolean(element.querySelector(`${name}-trigger`))
+  );
+}
+
+function impactCompare(a: ImpactValue, b: ImpactValue) {
+  const impactOrder = [null, 'minor', 'moderate', 'serious', 'critical'];
+  return impactOrder.indexOf(a) - impactOrder.indexOf(b);
+}
+
+export function transformViolations(violations: typeof AxeResults.violations, name: string) {
+  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;
+
+      if (element && !isInIframe && !maybeCausedByAccented(violation.id, element, name)) {
+        const issue: Issue = {
+          id: violation.id,
+          title: violation.help,
+          description: node.failureSummary ?? violation.description,
+          url: violation.helpUrl,
+          impact: violation.impact ?? null,
+        };
+        const existingElement = elementsWithIssues.find(
+          (elementWithIssues) => elementWithIssues.element === element,
+        );
+        if (existingElement === undefined) {
+          elementsWithIssues.push({
+            element,
+            rootNode: element.getRootNode(),
+            issues: [issue],
+          });
+        } else {
+          existingElement.issues.push(issue);
+        }
+      }
+    }
+  }
+
+  for (const elementWithIssues of elementsWithIssues) {
+    elementWithIssues.issues.sort((a, b) => {
+      return -impactCompare(a.impact, b.impact) || a.id.localeCompare(b.id);
+    });
+  }
+
+  return elementsWithIssues;
+}

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

@@ -0,0 +1,371 @@
+import assert from 'node:assert/strict';
+import { suite, test } from 'node:test';
+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 { AccentedTrigger } from '../elements/accented-trigger';
+type Violation = AxeResults['violations'][number];
+type AxeNode = Violation['nodes'][number];
+
+const win: Window & { CSS: typeof CSS } = {
+  document: {
+    // @ts-expect-error the return value is of incorrect type.
+    createElement: () => ({
+      style: {
+        setProperty: () => {},
+      },
+      dataset: {},
+    }),
+    contains: () => true,
+  },
+  // @ts-expect-error we're missing a lot of properties
+  getComputedStyle: () => ({
+    zIndex: '',
+    direction: 'ltr',
+    getPropertyValue: () => 'none',
+  }),
+  // @ts-expect-error we're missing a lot of properties
+  CSS: {
+    supports: () => true,
+  },
+};
+
+const getBoundingClientRect = () => ({});
+
+const getRootNode = (): Node => ({}) as Node;
+
+const baseElement = {
+  getBoundingClientRect,
+  getRootNode,
+  style: {
+    getPropertyValue: () => '',
+  },
+  closest: () => null,
+};
+
+// @ts-expect-error element is not HTMLElement
+const element1: HTMLElement = { ...baseElement, isConnected: true };
+// @ts-expect-error element is not HTMLElement
+const element2: HTMLElement = { ...baseElement, isConnected: true };
+// @ts-expect-error element is not HTMLElement
+const element3: HTMLElement = { ...baseElement, isConnected: false };
+
+// @ts-expect-error rootNode is not Node
+const rootNode: Node = {};
+
+const trigger = win.document.createElement('accented-trigger') as AccentedTrigger;
+
+const position = signal({
+  left: 0,
+  width: 100,
+  top: 0,
+  height: 100,
+});
+
+const visible = signal(true);
+
+const scrollableAncestors = signal(new Set<HTMLElement>());
+
+const commonNodeProps = {
+  html: '<div></div>',
+  any: [],
+  all: [],
+  none: [],
+  target: ['div'],
+};
+
+const node1: AxeNode = {
+  ...commonNodeProps,
+  element: element1,
+};
+
+const node2: AxeNode = {
+  ...commonNodeProps,
+  element: element2,
+};
+
+const node3: AxeNode = {
+  ...commonNodeProps,
+  element: element3,
+};
+
+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 violation4: Violation = {
+  ...commonViolationProps,
+  id: 'id4',
+  nodes: [node3],
+};
+
+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,
+};
+
+const scanContext = {
+  include: [win.document],
+  exclude: [],
+};
+
+suite('updateElementsWithIssues', () => {
+  test('no changes', () => {
+    const extendedElementsWithIssues: Signal<Array<ExtendedElementWithIssues>> = signal([
+      {
+        id: 1,
+        element: element1,
+        rootNode,
+        skipRender: false,
+        position,
+        visible,
+        trigger,
+        anchorNameValue: 'none',
+        scrollableAncestors,
+        issues: signal([issue1]),
+      },
+      {
+        id: 2,
+        element: element2,
+        rootNode,
+        skipRender: false,
+        position,
+        visible,
+        trigger,
+        anchorNameValue: 'none',
+        scrollableAncestors,
+        issues: signal([issue2]),
+      },
+    ]);
+    updateElementsWithIssues({
+      extendedElementsWithIssues,
+      scanContext,
+      violations: [violation1, violation2],
+      win,
+      name: '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,
+        rootNode,
+        skipRender: false,
+        position,
+        visible,
+        trigger,
+        anchorNameValue: 'none',
+        scrollableAncestors,
+        issues: signal([issue1]),
+      },
+      {
+        id: 2,
+        element: element2,
+        rootNode,
+        skipRender: false,
+        position,
+        visible,
+        trigger,
+        anchorNameValue: 'none',
+        scrollableAncestors,
+        issues: signal([issue2]),
+      },
+    ]);
+    updateElementsWithIssues({
+      extendedElementsWithIssues,
+      scanContext,
+      violations: [violation1, violation2, violation3],
+      win,
+      name: '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,
+        rootNode,
+        skipRender: false,
+        position,
+        visible,
+        trigger,
+        anchorNameValue: 'none',
+        scrollableAncestors,
+        issues: signal([issue1]),
+      },
+      {
+        id: 2,
+        element: element2,
+        rootNode,
+        skipRender: false,
+        position,
+        visible,
+        trigger,
+        anchorNameValue: 'none',
+        scrollableAncestors,
+        issues: signal([issue2, issue3]),
+      },
+    ]);
+    updateElementsWithIssues({
+      extendedElementsWithIssues,
+      scanContext,
+      violations: [violation1, violation2],
+      win,
+      name: '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,
+        rootNode,
+        skipRender: false,
+        position,
+        visible,
+        trigger,
+        anchorNameValue: 'none',
+        scrollableAncestors,
+        issues: signal([issue1]),
+      },
+    ]);
+    updateElementsWithIssues({
+      extendedElementsWithIssues,
+      scanContext,
+      violations: [violation1, violation2],
+      win,
+      name: '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 disconnected element added', () => {
+    const extendedElementsWithIssues: Signal<Array<ExtendedElementWithIssues>> = signal([
+      {
+        id: 1,
+        element: element1,
+        rootNode,
+        skipRender: false,
+        position,
+        visible,
+        trigger,
+        anchorNameValue: 'none',
+        scrollableAncestors,
+        issues: signal([issue1]),
+      },
+    ]);
+    updateElementsWithIssues({
+      extendedElementsWithIssues,
+      scanContext,
+      violations: [violation1, violation4],
+      win,
+      name: 'accented',
+    });
+    assert.equal(extendedElementsWithIssues.value.length, 1);
+    assert.equal(extendedElementsWithIssues.value[0]?.element, element1);
+  });
+
+  test('one element removed', () => {
+    const extendedElementsWithIssues: Signal<Array<ExtendedElementWithIssues>> = signal([
+      {
+        id: 1,
+        element: element1,
+        rootNode,
+        skipRender: false,
+        position,
+        visible,
+        trigger,
+        anchorNameValue: 'none',
+        scrollableAncestors,
+        issues: signal([issue1]),
+      },
+      {
+        id: 2,
+        element: element2,
+        rootNode,
+        skipRender: false,
+        position,
+        visible,
+        trigger,
+        anchorNameValue: 'none',
+        scrollableAncestors,
+        issues: signal([issue2]),
+      },
+    ]);
+    updateElementsWithIssues({
+      extendedElementsWithIssues,
+      scanContext,
+      violations: [violation1],
+      win,
+      name: 'accented',
+    });
+    assert.equal(extendedElementsWithIssues.value.length, 1);
+    assert.equal(extendedElementsWithIssues.value[0]?.element, element1);
+    assert.equal(extendedElementsWithIssues.value[0]?.issues.value.length, 1);
+  });
+});