accented 0.0.1-dev.4 → 0.0.2

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

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

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 && !Array.isArray(source[key])) {
+      if (!(key in target)) {
+        output[key] = source[key];
+      } else {
+        output[key] = deepMerge(target[key], source[key]);
+      }
+    }
+    else {
+      output[key] = source[key];
+    }
+  }
+  return output;
+}

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

@@ -0,0 +1,13 @@
+export default 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;
+  }
+  return outerHtml.slice(0, index) + '…' + outerHtml.slice(index + innerHtml.length);
+}

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

@@ -0,0 +1,21 @@
+import type { Position } from '../types';
+
+export default function getElementPosition(element: Element, win: Window): Position {
+  const rect = element.getBoundingClientRect();
+  const direction = win.getComputedStyle(element).direction;
+  if (direction === 'ltr') {
+    return {
+      inlineEndLeft: rect.right,
+      blockStartTop: rect.top,
+      direction
+    };
+  } else if (direction === 'rtl') {
+    return {
+      inlineEndLeft: rect.left,
+      blockStartTop: rect.top,
+      direction
+    };
+  } else {
+    throw new Error(`The element ${element} has a direction "${direction}", which is not supported.`);
+  }
+}

package/src/utils/get-scrollable-ancestors.ts

@@ -0,0 +1,14 @@
+const scrollableOverflowValues = new Set(['auto', 'scroll', 'hidden']);
+
+export default function getScrollableAncestors (element: HTMLElement, win: Window) {
+  let currentElement = element;
+  let scrollableAncestors = new Set<HTMLElement>();
+  while (currentElement.parentElement) {
+    currentElement = currentElement.parentElement;
+    const computedStyle = win.getComputedStyle(currentElement);
+    if (scrollableOverflowValues.has(computedStyle.overflowX) || scrollableOverflowValues.has(computedStyle.overflowY)) {
+      scrollableAncestors.add(currentElement);
+    }
+  }
+  return scrollableAncestors;
+};

package/src/utils/recalculate-positions.ts

@@ -0,0 +1,27 @@
+import { batch } from '@preact/signals-core';
+import { extendedElementsWithIssues } from '../state.js';
+import getElementPosition from './get-element-position.js';
+import logAndRethrow from '../log-and-rethrow.js';
+
+let frameRequested = false;
+
+export default function recalculatePositions() {
+  if (frameRequested) {
+    return;
+  }
+  frameRequested = true;
+  window.requestAnimationFrame(() => {
+    try {
+      frameRequested = false;
+      batch(() => {
+        extendedElementsWithIssues.value.forEach(({ element, position, visible }) => {
+          if (visible.value && element.isConnected) {
+            position.value = getElementPosition(element, window);
+          }
+        });
+      });
+    } catch (error) {
+      logAndRethrow(error);
+    }
+  });
+}

package/src/utils/recalculate-scrollable-ancestors.ts

@@ -0,0 +1,13 @@
+import { batch } from '@preact/signals-core';
+import { extendedElementsWithIssues } from '../state.js';
+import getScrollableAncestors from './get-scrollable-ancestors.js';
+
+export default function recalculateScrollableAncestors() {
+  batch(() => {
+    extendedElementsWithIssues.value.forEach(({ element, scrollableAncestors }) => {
+      if (element.isConnected) {
+        scrollableAncestors.value = getScrollableAncestors(element, window);
+      }
+    });
+  });
+}

package/src/utils/supports-anchor-positioning.ts

@@ -0,0 +1,7 @@
+type WindowWithCSS = Window & {
+  CSS: typeof CSS
+}
+
+export default function supportsAnchorPositioning(win: WindowWithCSS) {
+  return win.CSS.supports('anchor-name: --foo') && win.CSS.supports('position-anchor: --foo');
+}

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,56 @@
+import type { AxeResults, ImpactValue } from 'axe-core';
+import type { Issue, ElementWithIssues } from '../types';
+
+function impactCompare(a: ImpactValue, b: ImpactValue) {
+  const impactOrder = [null, 'minor', 'moderate', 'serious', 'critical'];
+  return impactOrder.indexOf(a) - impactOrder.indexOf(b);
+}
+
+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);
+        }
+      }
+    }
+  }
+
+  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,283 @@
+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 { AccentedTrigger } from '../elements/accented-trigger';
+type Violation = AxeResults['violations'][number];
+type Node = Violation['nodes'][number];
+
+const win: Window & { CSS: typeof CSS } = {
+  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: '',
+    direction: 'ltr'
+  }),
+  // @ts-expect-error we're missing a lot of properties
+  CSS: {
+    supports: () => true
+  }
+}
+
+const getBoundingClientRect = () => ({});
+
+// @ts-expect-error element is not HTMLElement
+const element1: HTMLElement = {getBoundingClientRect, isConnected: true};
+// @ts-expect-error element is not HTMLElement
+const element2: HTMLElement = {getBoundingClientRect, isConnected: true};
+// @ts-expect-error element is not HTMLElement
+const element3: HTMLElement = {getBoundingClientRect, isConnected: false};
+
+const trigger = win.document.createElement('accented-trigger') as AccentedTrigger;
+
+const position = signal({
+  inlineEndLeft: 0,
+  blockStartTop: 0,
+  direction: 'ltr' as const
+});
+
+const visible = signal(true);
+
+const scrollableAncestors = signal(new Set<HTMLElement>());
+
+const commonNodeProps = {
+  html: '<div></div>',
+  any: [],
+  all: [],
+  none: [],
+  target: ['div']
+};
+
+const node1: Node = {
+  ...commonNodeProps,
+  element: element1,
+};
+
+const node2: Node = {
+  ...commonNodeProps,
+  element: element2,
+};
+
+const node3: Node = {
+  ...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
+};
+
+suite('updateElementsWithIssues', () => {
+  test('no changes', () => {
+    const extendedElementsWithIssues: Signal<Array<ExtendedElementWithIssues>> = signal([
+      {
+        id: 1,
+        element: element1,
+        position,
+        visible,
+        trigger,
+        scrollableAncestors,
+        issues: signal([issue1])
+      },
+      {
+        id: 2,
+        element: element2,
+        position,
+        visible,
+        trigger,
+        scrollableAncestors,
+        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,
+        position,
+        visible,
+        trigger,
+        scrollableAncestors,
+        issues: signal([issue1])
+      },
+      {
+        id: 2,
+        element: element2,
+        position,
+        visible,
+        trigger,
+        scrollableAncestors,
+        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,
+        position,
+        visible,
+        trigger,
+        scrollableAncestors,
+        issues: signal([issue1])
+      },
+      {
+        id: 2,
+        element: element2,
+        position,
+        visible,
+        trigger,
+        scrollableAncestors,
+        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,
+        position,
+        visible,
+        trigger,
+        scrollableAncestors,
+        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 disconnected element added', () => {
+    const extendedElementsWithIssues: Signal<Array<ExtendedElementWithIssues>> = signal([
+      {
+        id: 1,
+        element: element1,
+        position,
+        visible,
+        trigger,
+        scrollableAncestors,
+        issues: signal([issue1])
+      }
+    ]);
+    updateElementsWithIssues(extendedElementsWithIssues, [violation1, violation4], win, '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,
+        position,
+        visible,
+        trigger,
+        scrollableAncestors,
+        issues: signal([issue1])
+      },
+      {
+        id: 2,
+        element: element2,
+        position,
+        visible,
+        trigger,
+        scrollableAncestors,
+        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);
+  });
+});