accented 1.0.1 → 1.1.1

package/src/elements/accented-dialog.ts

@@ -1,5 +1,15 @@
 import type { Signal } from '@preact/signals-core';
-import { colorDark, colorLight, fontSystemMono, fontSystemSans } from '../common/tokens.js';
+import {
+  colorDark,
+  colorFocus,
+  colorImpactCritical,
+  colorImpactMinor,
+  colorImpactModerate,
+  colorImpactSerious,
+  colorLight,
+  fontSystemMono,
+  fontSystemSans,
+} from '../common/tokens.js';
 import { accentedUrl } from '../constants.js';
 import { logAndRethrow } from '../log-and-rethrow.js';
 import type { Issue } from '../types.ts';
@@ -31,8 +41,6 @@ export const getAccentedDialog = () => {
         <p>
           Powered by
           <a href="${accentedUrl}" target="_blank" aria-description="Opens in new tab">Accented</a>
-          and
-          <a href="https://github.com/dequelabs/axe-core" target="_blank" aria-description="Opens in new tab">axe-core</a>.
         </p>
       </section>
     </dialog>
@@ -65,30 +73,13 @@ export const getAccentedDialog = () => {
       --background-color: light-dark(var(--light-color), var(--dark-color));
       --text-color: light-dark(var(--dark-color), var(--light-color));
 
-      --impact-lightness: 0.80;
-      --focus-lightness: 0.45;
-      @media (prefers-color-scheme: dark) {
-        --impact-lightness: 0.45;
-        --focus-lightness: 0.80;
-      }
-
-      --blue-hue: 230;
-      --gold-hue: 90;
-      --red-hue: 0;
-
       /* Contrasts with background. */
-      --focus-color: oklch(var(--focus-lightness) 0.25 var(--blue-hue));
-
-      --impact-chroma: 0.16;
-
-      --impact-moderate-hue: var(--blue-hue);
-      --impact-serious-hue: var(--gold-hue);
-      --impact-critical-hue: var(--red-hue);
+      --focus-color: ${colorFocus};
 
-      --impact-minor-color: oklch(var(--impact-lightness) 0 0);
-      --impact-moderate-color: oklch(var(--impact-lightness) var(--impact-chroma) var(--impact-moderate-hue));
-      --impact-serious-color: oklch(var(--impact-lightness) var(--impact-chroma) var(--impact-serious-hue));
-      --impact-critical-color: oklch(var(--impact-lightness) var(--impact-chroma) var(--impact-critical-hue));
+      --impact-minor-color: ${colorImpactMinor};
+      --impact-moderate-color: ${colorImpactModerate};
+      --impact-serious-color: ${colorImpactSerious};
+      --impact-critical-color: ${colorImpactCritical};
 
       --base-size: max(1rem, 16px);
 

package/src/logger.ts

@@ -1,36 +1,290 @@
 import { effect } from '@preact/signals-core';
-import { accentedUrl } from './constants.js';
+import {
+  consoleColorImpactCritical,
+  consoleColorImpactMinor,
+  consoleColorImpactModerate,
+  consoleColorImpactSerious,
+} from './common/tokens.js';
+import { accentedUrl, orderedImpacts } from './constants.js';
 import { elementsWithIssues, enabled } from './state.js';
-import type { ElementWithIssues } from './types.ts';
+import type { ElementWithIssues, Issue } from './types.ts';
+import { areElementsWithIssuesEqual } from './utils/are-elements-with-issues-equal.js';
+import { areIssueSetsEqual } from './utils/are-issue-sets-equal.js';
+import { areIssuesEqual } from './utils/are-issues-equal.js';
 
-function filterPropsForOutput(elements: Array<ElementWithIssues>) {
-  return elements.map(({ element, issues }) => ({ element, issues }));
+// For user friendliness, we want to balance two things:
+// * the user shouldn't have to click in the console too many times to get to the info they need;
+// * the output should be concise and not overwhelm the user with too much information at once.
+// This number is chosen as a compromise between these two factors.
+const MAX_ISSUES_BEFORE_OUTPUT_COLLAPSE = 5;
+
+// Groups have bold color by default in the console.
+// This doesn't seem appropriate for our purposes, so we have to explicitly set the normal font weight.
+const defaultStyle = 'font-weight: normal;';
+
+// We'll use the same colors in the console as in the dialog UI
+// (except the theme will be reversed since in the dialog, the color needs to have enough contrast against text color,
+// and in the console, the color needs to have enough contrast against the background color).
+const colors = {
+  minor: consoleColorImpactMinor,
+  moderate: consoleColorImpactModerate,
+  serious: consoleColorImpactSerious,
+  critical: consoleColorImpactCritical,
+};
+
+const uppercasedImpactText = (impact: Issue['impact']) =>
+  impact.charAt(0).toUpperCase() + impact.slice(1);
+
+const titleAndUrl = (issue: { title: Issue['title']; url: Issue['url'] }) =>
+  `${issue.title} ${issue.url}`;
+
+// This sorting is not ideal since it doesn't work very well with shadow DOM.
+const sortByElementPositions = (
+  a: ElementWithIssues['element'],
+  b: ElementWithIssues['element'],
+) => (a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_PRECEDING ? 1 : -1);
+
+type IssueType = {
+  title: Issue['title'];
+  url: Issue['url'];
+  impact: Issue['impact'];
+  elements: Array<{ element: ElementWithIssues['element']; description: Issue['description'] }>;
+};
+
+type GroupedByIssueType = Record<string, IssueType>;
+
+const getIssueTypeGroups = (elementsWithIssues: Array<ElementWithIssues>) => {
+  const groupedByIssueType = elementsWithIssues.reduce((acc, { element, issues }) => {
+    for (const issue of issues) {
+      if (!acc[issue.id]) {
+        acc[issue.id] = {
+          title: issue.title,
+          url: issue.url,
+          impact: issue.impact,
+          elements: [],
+        };
+      }
+      acc[issue.id]?.elements.push({ element, description: issue.description });
+    }
+    return acc;
+  }, {} as GroupedByIssueType);
+
+  const sorted = Object.values(groupedByIssueType).sort((a, b) => {
+    const impactComparison = orderedImpacts.indexOf(b.impact) - orderedImpacts.indexOf(a.impact);
+    if (impactComparison !== 0) {
+      return impactComparison;
+    }
+    return b.elements.length - a.elements.length;
+  });
+
+  return sorted;
+};
+
+function logIssuesByElement(elementsWithIssues: Array<ElementWithIssues>) {
+  // Elements with more severe issues (or with a higher number of issues of the same severity)
+  // will appear higher in the output.
+  // This way, issues with a higher severity will be prioritized.
+  const sortedElementsWithIssues = elementsWithIssues.toSorted((a, b) => {
+    const impacts = orderedImpacts.toReversed();
+    const impactWithDifferentIssueCount = impacts.find((impact) => {
+      const aCount = a.issues.filter((issue) => issue.impact === impact).length;
+      const bCount = b.issues.filter((issue) => issue.impact === impact).length;
+      return aCount !== bCount;
+    });
+    if (impactWithDifferentIssueCount) {
+      const aCount = a.issues.filter(
+        (issue) => issue.impact === impactWithDifferentIssueCount,
+      ).length;
+      const bCount = b.issues.filter(
+        (issue) => issue.impact === impactWithDifferentIssueCount,
+      ).length;
+      return bCount - aCount; // Sort by count of issues with the same impact
+    }
+    return sortByElementPositions(a.element, b.element);
+  });
+
+  for (const { element, issues } of sortedElementsWithIssues) {
+    const sortedAndFilteredImpacts = orderedImpacts
+      .toReversed()
+      .filter((impact) => issues.some((issue) => issue.impact === impact));
+
+    const issuesWithImpacts = sortedAndFilteredImpacts
+      .map((impact) => `%c${issues.filter((issue) => issue.impact === impact).length} ${impact}`)
+      .join(', ');
+
+    const baseOutput = `${issuesWithImpacts}%c`;
+    const output =
+      issues.length === 1 && issues[0]
+        ? `${baseOutput}\n${titleAndUrl(issues[0])}\n%o`
+        : `${baseOutput}\n%o`;
+
+    console.groupCollapsed(
+      output,
+      ...sortedAndFilteredImpacts.map((impact) => `color: ${colors[impact]};`),
+      defaultStyle,
+      element,
+    );
+
+    if (issues.length === 1) {
+      // If an element has just one issue, output that issue inline, to reduce the number of clicks in the console for the user.
+      console.log(issues[0]?.description);
+    } else {
+      for (const issue of issues) {
+        console.groupCollapsed(
+          `%c${uppercasedImpactText(issue.impact)}:%c\n${titleAndUrl(issue)}`,
+          `color: ${colors[issue.impact]};`,
+          defaultStyle,
+        );
+        console.log(issue.description);
+        console.groupEnd();
+      }
+    }
+    console.groupEnd();
+  }
+}
+
+function logIssuesByType(issueTypeGroups: Array<IssueType>) {
+  for (const { title, url, impact, elements } of issueTypeGroups) {
+    // We'll output the element itself next to the issue description if there's just one associated element,
+    // to reduce the number of clicks in the console for the user.
+    const shouldOutputElementInline = elements.length === 1;
+    const baseOutput = `%c${uppercasedImpactText(impact)} (${elements.length} element${elements.length === 1 ? '' : 's'}):%c\n${titleAndUrl({ title, url })}`;
+    const output = shouldOutputElementInline ? `${baseOutput}\n%o` : baseOutput;
+    console.groupCollapsed(
+      output,
+      `color: ${colors[impact]};`,
+      defaultStyle,
+      ...(shouldOutputElementInline ? [elements[0]?.element] : []),
+    );
+    if (shouldOutputElementInline) {
+      console.log(elements[0]?.description);
+    } else {
+      for (const { element, description } of elements.sort((elementContainer1, elementContainer2) =>
+        sortByElementPositions(elementContainer1.element, elementContainer2.element),
+      )) {
+        console.groupCollapsed('%o', element);
+        console.log(description);
+        console.groupEnd();
+      }
+    }
+    console.groupEnd();
+  }
+}
+
+function logNewIssues(
+  elementsWithIssues: Array<ElementWithIssues>,
+  previousElementsWithIssues: Array<ElementWithIssues>,
+) {
+  // The elements with accessibility issues that didn't have any associated issues
+  // or that weren't in the DOM at the time of last scan.
+  const addedElements = elementsWithIssues.filter((elementWithIssues) => {
+    return !previousElementsWithIssues.some((previousElementWithIssues) =>
+      areElementsWithIssuesEqual(previousElementWithIssues, elementWithIssues),
+    );
+  });
+
+  // The elements that now have more issues than at the time of last scan,
+  // with just the new issues (previously existing issues are filtered out).
+  const existingElementsWithNewIssues = elementsWithIssues.reduce<Array<ElementWithIssues>>(
+    (acc, elementWithIssues) => {
+      let foundElementWithIssues: ElementWithIssues | null = null;
+      for (const previousElementWithIssues of previousElementsWithIssues) {
+        if (
+          areElementsWithIssuesEqual(previousElementWithIssues, elementWithIssues) &&
+          !areIssueSetsEqual(previousElementWithIssues.issues, elementWithIssues.issues)
+        ) {
+          const newIssues = elementWithIssues.issues.filter((issue) => {
+            return !previousElementWithIssues.issues.some((prevIssue) =>
+              areIssuesEqual(prevIssue, issue),
+            );
+          });
+          if (newIssues.length > 0) {
+            foundElementWithIssues = {
+              ...elementWithIssues,
+              issues: newIssues,
+            };
+            acc.push(foundElementWithIssues);
+          }
+          break;
+        }
+      }
+      return acc;
+    },
+    [],
+  );
+
+  const elementsWithNewIssues = [...addedElements, ...existingElementsWithNewIssues];
+  const newIssueCount = elementsWithNewIssues.reduce((acc, { issues }) => acc + issues.length, 0);
+  if (newIssueCount === 0) {
+    console.log('No new issues');
+  } else {
+    const newIssuesMessage = `%cNew issues (${newIssueCount} in ${elementsWithNewIssues.length} element${elementsWithNewIssues.length === 1 ? '' : 's'})`;
+    if (newIssueCount <= MAX_ISSUES_BEFORE_OUTPUT_COLLAPSE) {
+      // Don't collapse the new issues if there are not too many (this hopefully helps user avoid unnecessary clicks in the console).
+      console.group(newIssuesMessage, defaultStyle);
+    } else {
+      console.groupCollapsed(newIssuesMessage, defaultStyle);
+    }
+    // Output by element (no specific reason for this choice, just a preference).
+    logIssuesByElement(elementsWithNewIssues);
+    console.groupEnd();
+  }
+}
+
+function logIssues(
+  elementsWithIssues: Array<ElementWithIssues>,
+  previousElementsWithIssues: Array<ElementWithIssues>,
+) {
+  const elementCount = elementsWithIssues.length;
+
+  if (elementCount === 0) {
+    console.log(`No accessibility issues (Accented, ${accentedUrl}).`);
+    return;
+  }
+
+  const issueCount = elementsWithIssues.reduce((acc, { issues }) => acc + issues.length, 0);
+  console.group(
+    `%c${issueCount} accessibility issue${issueCount === 1 ? '' : 's'} in ${elementCount} element${elementCount === 1 ? '' : 's'} (Accented, ${accentedUrl}):\n`,
+    defaultStyle,
+  );
+
+  if (issueCount <= MAX_ISSUES_BEFORE_OUTPUT_COLLAPSE) {
+    // Don't collapse issues if there are not too many (this hopefully helps user avoid unnecessary clicks in the console).
+    // Output by element (no specific reason for this choice, just a preference).
+    logIssuesByElement(elementsWithIssues);
+  } else {
+    // When there are many issues, outputting them all would probably make the console too noisy,
+    // so we collapse them.
+    // Moreover, we output all issues twice, by element and by issue type, to give users more choice.
+    console.groupCollapsed(`%cAll by element (${elementsWithIssues.length})`, defaultStyle);
+    logIssuesByElement(elementsWithIssues);
+    console.groupEnd();
+
+    const issueTypeGroups = getIssueTypeGroups(elementsWithIssues);
+    console.groupCollapsed(`%cAll by issue type (${issueTypeGroups.length})`, defaultStyle);
+    logIssuesByType(issueTypeGroups);
+    console.groupEnd();
+  }
+
+  if (previousElementsWithIssues.length > 0) {
+    // Log new issues separately, to make it easier for the user to know what issues
+    // were introduced recently.
+    logNewIssues(elementsWithIssues, previousElementsWithIssues);
+  }
+
+  console.groupEnd();
 }
 
 export function createLogger() {
-  let firstRun = true;
+  let previousElementsWithIssues: Array<ElementWithIssues> = [];
 
   return effect(() => {
     if (!enabled.value) {
       return;
     }
 
-    const elementCount = elementsWithIssues.value.length;
-    if (elementCount > 0) {
-      const issueCount = elementsWithIssues.value.reduce(
-        (acc, { issues }) => acc + issues.length,
-        0,
-      );
-      console.log(
-        `${issueCount} accessibility issue${issueCount === 1 ? '' : 's'} found in ${elementCount} element${issueCount === 1 ? '' : 's'} (Accented, ${accentedUrl}):\n`,
-        filterPropsForOutput(elementsWithIssues.value),
-      );
-    } else {
-      if (firstRun) {
-        firstRun = false;
-      } else {
-        console.log(`No accessibility issues found (Accented, ${accentedUrl}).`);
-      }
-    }
+    logIssues(elementsWithIssues.value, previousElementsWithIssues);
+
+    previousElementsWithIssues = elementsWithIssues.value;
   });
 }

package/src/types.ts

@@ -36,9 +36,40 @@ export type Output = {
   /**
    * Whether the list of elements with issues should be printed to the browser console whenever issues are added, removed, or changed.
    *
+   * **Example:**
+   *
+   * ```js
+   * accented({
+   *   output: {
+   *     console: false
+   *   }
+   * });
+   * ```
+   *
+   * In the example, the issues will not be logged to the console, while elements on the page will still be highlighted.
+   *
    * @default true
    * */
   console?: boolean;
+
+  /**
+   * Whether Accented should highlight elements with issues on the page.
+   *
+   * **Example:**
+   *
+   * ```js
+   * accented({
+   *   output: {
+   *     page: false
+   *   }
+   * });
+   * ```
+   *
+   * In the example, the issues will only be logged to the console, with no highlights on the page.
+   *
+   * @default true
+   * */
+  page?: boolean;
 };
 
 /**
@@ -229,7 +260,7 @@ export type Issue = {
   title: string;
   description: string;
   url: string;
-  impact: axe.ImpactValue;
+  impact: Exclude<axe.ImpactValue, null>;
 };
 
 export type BaseElementWithIssues = {

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

@@ -1,12 +1,9 @@
 import type { Issue } from '../types.ts';
-
-const issueProps: Array<keyof Issue> = ['id', 'title', 'description', 'url', 'impact'];
+import { areIssuesEqual } from './are-issues-equal.js';
 
 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]))),
-    )
+    issues1.every((issue1) => Boolean(issues2.find((issue2) => areIssuesEqual(issue1, issue2))))
   );
 }

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

@@ -0,0 +1,7 @@
+import type { Issue } from '../types.ts';
+
+const issueProps: Array<keyof Issue> = ['id', 'title', 'description', 'url', 'impact'];
+
+export function areIssuesEqual(issue1: Issue, issue2: Issue) {
+  return issueProps.every((prop) => issue2[prop] === issue1[prop]);
+}

package/src/utils/transform-violations.ts

@@ -1,4 +1,5 @@
-import type { AxeResults, ImpactValue } from 'axe-core';
+import type { AxeResults } from 'axe-core';
+import { issuesUrl, orderedImpacts } from '../constants.js';
 import type { ElementWithIssues, Issue } from '../types.ts';
 
 // This is a list of axe-core violations (their ids) that may be flagged by axe-core
@@ -20,9 +21,8 @@ function maybeCausedByAccented(violationId: string, element: HTMLElement, name:
   );
 }
 
-function impactCompare(a: ImpactValue, b: ImpactValue) {
-  const impactOrder = [null, 'minor', 'moderate', 'serious', 'critical'];
-  return impactOrder.indexOf(a) - impactOrder.indexOf(b);
+function impactCompare(a: Issue['impact'], b: Issue['impact']) {
+  return orderedImpacts.indexOf(a) - orderedImpacts.indexOf(b);
 }
 
 export function transformViolations(violations: typeof AxeResults.violations, name: string) {
@@ -41,14 +41,20 @@ export function transformViolations(violations: typeof AxeResults.violations, na
       const isInIframe = target.length > 1;
 
       if (element && !isInIframe && !maybeCausedByAccented(violation.id, element, name)) {
+        if (!violation.impact) {
+          console.warn(
+            `Accented: axe-core (the accessibility testing engine) returned a violation with an empty impact. This may be a bug in axe-core or in Accented. Please report it at ${issuesUrl}.`,
+            violation,
+          );
+          continue;
+        }
         const issue: Issue = {
           id: violation.id,
           title: violation.help,
           // See https://github.com/pomerantsev/accented/issues/203
           description: node.failureSummary ?? violation.description,
           url: violation.helpUrl,
-          // See https://github.com/pomerantsev/accented/issues/203
-          impact: violation.impact ?? null,
+          impact: violation.impact,
         };
         const existingElement = elementsWithIssues.find(
           (elementWithIssues) => elementWithIssues.element === element,

package/src/validate-options.ts

@@ -149,6 +149,11 @@ export function validateOptions(options: AccentedOptions) {
         `Accented: invalid argument. \`output.console\` option is expected to be a boolean. It’s currently set to ${options.output.console}.`,
       );
     }
+    if (options.output.page !== undefined && typeof options.output.page !== 'boolean') {
+      console.warn(
+        `Accented: invalid argument. \`output.page\` option is expected to be a boolean. It’s currently set to ${options.output.page}.`,
+      );
+    }
   }
   if (options.callback !== undefined && typeof options.callback !== 'function') {
     throw new TypeError(