abledom 0.6.1 → 0.6.3

package/README.md

@@ -1,9 +1,99 @@
 # AbleDOM
 
-Continuous detection of typical web application accessibility problems.
+A continuous accessibility (a11y) monitor for modern web applications.
+
+AbleDOM is a lightweight JavaScript/TypeScript library that observes your DOM in real-time and detects common accessibility issues as they appear.
 
 _Here be dragons_.
 
+## Installation
+
+```bash
+npm install abledom
+# or
+yarn add abledom
+# or
+pnpm add abledom
+```
+
+## Quick start
+
+```typescript
+import { AbleDOM } from "abledom";
+
+const _ableDOM = new AbleDOM(window, { log: window.console?.error });
+
+// ...Create and add rules and exceptions
+```
+
+### Using rules
+
+```typescript
+import { AbleDOM, ContrastRule } from "abledom";
+
+const contrastRule = new ContrastRule();
+this._ableDOM.addRule(contrastRule);
+```
+
+### Adding valid exceptions
+
+```typescript
+import { AbleDOM, ContrastRule } from "abledom";
+
+const contrastExceptions: ((element: HTMLElement) => boolean)[] = [
+  (element: HTMLElement) => {
+    return element.style?.display === "none";
+  },
+  (element: HTMLElement) => {
+    return element.datalist?.ignore === "true";
+  },
+];
+
+const contrastRule = new ContrastRule();
+
+contrastExceptions.forEach((exception) => contrastRule.addException(exception));
+
+this._ableDOM.addRule(contrastRule);
+```
+
+## Rules
+
+### AtomicRule
+
+Detects focusable elements nested inside other atomic focusable elements (like buttons, links, or inputs). Prevents confusing interactive hierarchies that can break keyboard navigation and assistive technology functionality.
+
+### BadFocusRule
+
+Monitors focus changes to detect when focus is stolen by invisible elements. Helps identify scenarios where focus moves to elements that users cannot see, creating a poor accessibility experience.
+
+### ContrastRule
+
+Validates color contrast ratios between text and background colors according to WCAG standards. Ensures text meets minimum contrast requirements (4.5:1 for normal text, 3:1 for large text) for readability.
+
+### ExistingIdRule
+
+Verifies that elements referenced by `aria-labelledby`, `aria-describedby`, or `<label for>` attributes actually exist in the DOM. Prevents broken accessibility relationships.
+
+### FocusableElementLabelRule
+
+Ensures all focusable interactive elements have accessible labels. Checks for labels through various methods including `<label>` elements, ARIA attributes, alt text, and visible text content.
+
+### FocusLostRule
+
+Detects when keyboard focus is lost without being moved to another valid element. Monitors focus/blur events to catch scenarios where users might lose their place while navigating with keyboard.
+
+### NestedInteractiveElementRule
+
+Identifies interactive elements nested within other interactive elements (e.g., a button inside a link). This pattern can confuse users and assistive technologies about which element to interact with.
+
+### RequiredParentRule
+
+Validates that elements requiring specific parent elements are properly nested. Enforces correct HTML structure for elements like `<li>` (must be in `<ul>` or `<ol>`), table elements, and ARIA roles that have parent requirements.
+
+### TabIndexRule
+
+Warns about problematic uses of the `tabindex` attribute, including positive values that break natural tab order and `tabindex` on non-interactive elements. Promotes accessible keyboard navigation patterns.
+
 ## Contributing
 
 This project welcomes contributions and suggestions. Most contributions require you to agree to a

package/dist/esm/index.js

@@ -57,10 +57,10 @@ var ValidationRule = class {
   }
 };
 
-// inline-file:/Users/marata/Documents/Work/abledom/src/ui/ui.css
+// inline-file:/Users/marata/tmp/abledom/src/ui/ui.css
 var ui_default = "#abledom-report {\n  bottom: 20px;\n  display: flex;\n  flex-direction: column;\n  left: 10px;\n  max-height: 80%;\n  max-width: 60%;\n  padding: 4px 8px;\n  position: fixed;\n  z-index: 100500;\n}\n\n#abledom-report :focus-visible {\n  outline: 3px solid red;\n  mix-blend-mode: difference;\n}\n\n#abledom-report.abledom-align-left {\n  left: 10px;\n  right: auto;\n}\n\n#abledom-report.abledom-align-right {\n  left: auto;\n  right: 10px;\n}\n\n#abledom-report.abledom-align-bottom {\n  bottom: 20px;\n  top: auto;\n}\n\n#abledom-report.abledom-align-top {\n  /* flex-direction: column-reverse; */\n  bottom: auto;\n  top: 10px;\n}\n\n.abledom-menu-container {\n  backdrop-filter: blur(3px);\n  border-radius: 8px;\n  box-shadow: 0px 0px 4px rgba(127, 127, 127, 0.5);\n  display: inline-block;\n  margin: 2px auto 2px 0;\n}\n\n#abledom-report.abledom-align-right .abledom-menu-container {\n  margin: 2px 0 2px auto;\n}\n\n.abledom-menu {\n  background-color: rgba(140, 10, 121, 0.7);\n  border-radius: 8px;\n  color: white;\n  display: inline flex;\n  font-family: Arial, Helvetica, sans-serif;\n  font-size: 16px;\n  line-height: 26px;\n  padding: 4px;\n}\n\n.abledom-menu .issues-count {\n  margin: 0 8px;\n  display: inline-block;\n}\n\n.abledom-menu .button {\n  all: unset;\n  color: #000;\n  cursor: pointer;\n  background: linear-gradient(\n    180deg,\n    rgba(255, 255, 255, 1) 0%,\n    rgba(200, 200, 200, 1) 100%\n  );\n  border-radius: 6px;\n  border: 1px solid rgba(255, 255, 255, 0.4);\n  box-sizing: border-box;\n  line-height: 0px;\n  margin-right: 4px;\n  max-height: 26px;\n  padding: 2px;\n  text-decoration: none;\n}\n\n.abledom-menu .align-button {\n  border-right-color: rgba(0, 0, 0, 0.4);\n  border-radius: 0;\n  margin: 0;\n}\n\n.abledom-menu .align-button:active,\n#abledom-report .pressed {\n  background: linear-gradient(\n    180deg,\n    rgba(130, 130, 130, 1) 0%,\n    rgba(180, 180, 180, 1) 100%\n  );\n}\n\n.abledom-menu .align-button-first {\n  border-top-left-radius: 6px;\n  border-bottom-left-radius: 6px;\n  margin-left: 8px;\n}\n.abledom-menu .align-button-last {\n  border-top-right-radius: 6px;\n  border-bottom-right-radius: 6px;\n  border-right-color: rgba(255, 255, 255, 0.4);\n}\n\n.abledom-issues-container {\n  overflow: auto;\n  max-height: calc(100vh - 100px);\n}\n\n#abledom-report.abledom-align-right .abledom-issues-container {\n  text-align: right;\n}\n\n.abledom-issue-container {\n  backdrop-filter: blur(3px);\n  border-radius: 8px;\n  box-shadow: 0px 0px 4px rgba(127, 127, 127, 0.5);\n  display: inline-flex;\n  margin: 2px 0;\n}\n\n.abledom-issue {\n  background-color: rgba(164, 2, 2, 0.7);\n  border-radius: 8px;\n  color: white;\n  display: inline flex;\n  font-family: Arial, Helvetica, sans-serif;\n  font-size: 16px;\n  line-height: 26px;\n  padding: 4px;\n}\n.abledom-issue_warning {\n  background-color: rgba(163, 82, 1, 0.7);\n}\n.abledom-issue_info {\n  background-color: rgba(0, 0, 255, 0.7);\n}\n\n.abledom-issue .button {\n  all: unset;\n  color: #000;\n  cursor: pointer;\n  background: linear-gradient(\n    180deg,\n    rgba(255, 255, 255, 1) 0%,\n    rgba(200, 200, 200, 1) 100%\n  );\n  border-radius: 6px;\n  border: 1px solid rgba(255, 255, 255, 0.4);\n  box-sizing: border-box;\n  line-height: 0px;\n  margin-right: 4px;\n  max-height: 26px;\n  padding: 2px;\n  text-decoration: none;\n}\n\n.abledom-issue .button:hover {\n  opacity: 0.7;\n}\n\n.abledom-issue .button.close {\n  background: none;\n  border-color: transparent;\n  color: #fff;\n  margin: 0;\n}\n";
 
-// inline-file:/Users/marata/Documents/Work/abledom/src/ui/highlighter.css
+// inline-file:/Users/marata/tmp/abledom/src/ui/highlighter.css
 var highlighter_default = ".abledom-highlight {\n  background-color: yellow;\n  box-sizing: border-box;\n  display: none;\n  opacity: 0.6;\n  position: fixed;\n  z-index: 100499;\n}\n\n.abledom-highlight-border1 {\n  border-top: 2px solid red;\n  border-bottom: 2px solid red;\n  box-sizing: border-box;\n  position: absolute;\n  top: -2px;\n  width: calc(100% + 20px);\n  height: calc(100% + 4px);\n  margin: 0 -10px;\n}\n\n.abledom-highlight-border2 {\n  border-left: 2px solid red;\n  border-right: 2px solid red;\n  box-sizing: border-box;\n  position: absolute;\n  width: calc(100% + 4px);\n  left: -2px;\n  height: calc(100% + 20px);\n  margin: -10px 0;\n}\n";
 
 // src/ui/domBuilder.ts
@@ -118,7 +118,7 @@ var DOMBuilder = class {
   }
 };
 
-// inline-file:/Users/marata/Documents/Work/abledom/src/ui/close.svg
+// inline-file:/Users/marata/tmp/abledom/src/ui/close.svg
 var close_default = (function buildSVG(parent) {
   const builder = new DOMBuilder(parent);
   builder.openTag("svg", { "width": "20", "height": "20", "viewBox": "0 0 24 24", "fill": "none", "stroke": "currentColor", "stroke-width": "2", "stroke-linecap": "round", "stroke-linejoin": "round", "xmlns": "http://www.w3.org/2000/svg" }, void 0, "http://www.w3.org/2000/svg");
@@ -132,7 +132,7 @@ var close_default = (function buildSVG(parent) {
   return parent.firstElementChild;
 });
 
-// inline-file:/Users/marata/Documents/Work/abledom/src/ui/help.svg
+// inline-file:/Users/marata/tmp/abledom/src/ui/help.svg
 var help_default = (function buildSVG2(parent) {
   const builder = new DOMBuilder(parent);
   builder.openTag("svg", { "width": "20", "height": "20", "viewBox": "0 0 24 24", "fill": "none", "stroke": "currentColor", "stroke-width": "2", "stroke-linecap": "round", "stroke-linejoin": "round", "xmlns": "http://www.w3.org/2000/svg" }, void 0, "http://www.w3.org/2000/svg");
@@ -146,7 +146,7 @@ var help_default = (function buildSVG2(parent) {
   return parent.firstElementChild;
 });
 
-// inline-file:/Users/marata/Documents/Work/abledom/src/ui/log.svg
+// inline-file:/Users/marata/tmp/abledom/src/ui/log.svg
 var log_default = (function buildSVG3(parent) {
   const builder = new DOMBuilder(parent);
   builder.openTag("svg", { "width": "20", "height": "20", "viewBox": "0 0 24 24", "fill": "none", "stroke": "currentColor", "stroke-width": "2", "stroke-linecap": "round", "stroke-linejoin": "round", "xmlns": "http://www.w3.org/2000/svg" }, void 0, "http://www.w3.org/2000/svg");
@@ -158,7 +158,7 @@ var log_default = (function buildSVG3(parent) {
   return parent.firstElementChild;
 });
 
-// inline-file:/Users/marata/Documents/Work/abledom/src/ui/reveal.svg
+// inline-file:/Users/marata/tmp/abledom/src/ui/reveal.svg
 var reveal_default = (function buildSVG4(parent) {
   const builder = new DOMBuilder(parent);
   builder.openTag("svg", { "width": "20", "height": "20", "viewBox": "0 0 24 24", "fill": "none", "stroke": "currentColor", "stroke-width": "2", "stroke-linecap": "round", "stroke-linejoin": "round", "xmlns": "http://www.w3.org/2000/svg" }, void 0, "http://www.w3.org/2000/svg");
@@ -176,7 +176,7 @@ var reveal_default = (function buildSVG4(parent) {
   return parent.firstElementChild;
 });
 
-// inline-file:/Users/marata/Documents/Work/abledom/src/ui/bug.svg
+// inline-file:/Users/marata/tmp/abledom/src/ui/bug.svg
 var bug_default = (function buildSVG5(parent) {
   const builder = new DOMBuilder(parent);
   builder.openTag("svg", { "width": "20", "height": "20", "viewBox": "0 0 20 20", "fill": "none", "stroke": "currentColor" }, void 0, "http://www.w3.org/2000/svg");
@@ -204,7 +204,7 @@ var bug_default = (function buildSVG5(parent) {
   return parent.firstElementChild;
 });
 
-// inline-file:/Users/marata/Documents/Work/abledom/src/ui/hideall.svg
+// inline-file:/Users/marata/tmp/abledom/src/ui/hideall.svg
 var hideall_default = (function buildSVG6(parent) {
   const builder = new DOMBuilder(parent);
   builder.openTag("svg", { "width": "20", "height": "20", "viewBox": "0 0 20 20", "fill": "none", "stroke": "currentColor" }, void 0, "http://www.w3.org/2000/svg");
@@ -218,7 +218,7 @@ var hideall_default = (function buildSVG6(parent) {
   return parent.firstElementChild;
 });
 
-// inline-file:/Users/marata/Documents/Work/abledom/src/ui/muteall.svg
+// inline-file:/Users/marata/tmp/abledom/src/ui/muteall.svg
 var muteall_default = (function buildSVG7(parent) {
   const builder = new DOMBuilder(parent);
   builder.openTag("svg", { "width": "20", "height": "20", "viewBox": "0 0 20 20", "fill": "none", "stroke": "currentColor" }, void 0, "http://www.w3.org/2000/svg");
@@ -234,7 +234,7 @@ var muteall_default = (function buildSVG7(parent) {
   return parent.firstElementChild;
 });
 
-// inline-file:/Users/marata/Documents/Work/abledom/src/ui/showall.svg
+// inline-file:/Users/marata/tmp/abledom/src/ui/showall.svg
 var showall_default = (function buildSVG8(parent) {
   const builder = new DOMBuilder(parent);
   builder.openTag("svg", { "width": "20", "height": "20", "viewBox": "0 0 20 20", "fill": "none", "stroke": "currentColor" }, void 0, "http://www.w3.org/2000/svg");
@@ -246,7 +246,7 @@ var showall_default = (function buildSVG8(parent) {
   return parent.firstElementChild;
 });
 
-// inline-file:/Users/marata/Documents/Work/abledom/src/ui/aligntopleft.svg
+// inline-file:/Users/marata/tmp/abledom/src/ui/aligntopleft.svg
 var aligntopleft_default = (function buildSVG9(parent) {
   const builder = new DOMBuilder(parent);
   builder.openTag("svg", { "width": "20", "height": "20", "viewBox": "0 0 20 20", "fill": "none", "stroke": "currentColor" }, void 0, "http://www.w3.org/2000/svg");
@@ -256,7 +256,7 @@ var aligntopleft_default = (function buildSVG9(parent) {
   return parent.firstElementChild;
 });
 
-// inline-file:/Users/marata/Documents/Work/abledom/src/ui/aligntopright.svg
+// inline-file:/Users/marata/tmp/abledom/src/ui/aligntopright.svg
 var aligntopright_default = (function buildSVG10(parent) {
   const builder = new DOMBuilder(parent);
   builder.openTag("svg", { "width": "20", "height": "20", "viewBox": "0 0 20 20", "fill": "none", "stroke": "currentColor" }, void 0, "http://www.w3.org/2000/svg");
@@ -266,7 +266,7 @@ var aligntopright_default = (function buildSVG10(parent) {
   return parent.firstElementChild;
 });
 
-// inline-file:/Users/marata/Documents/Work/abledom/src/ui/alignbottomright.svg
+// inline-file:/Users/marata/tmp/abledom/src/ui/alignbottomright.svg
 var alignbottomright_default = (function buildSVG11(parent) {
   const builder = new DOMBuilder(parent);
   builder.openTag("svg", { "width": "20", "height": "20", "viewBox": "0 0 20 20", "fill": "none", "stroke": "currentColor" }, void 0, "http://www.w3.org/2000/svg");
@@ -276,7 +276,7 @@ var alignbottomright_default = (function buildSVG11(parent) {
   return parent.firstElementChild;
 });
 
-// inline-file:/Users/marata/Documents/Work/abledom/src/ui/alignbottomleft.svg
+// inline-file:/Users/marata/tmp/abledom/src/ui/alignbottomleft.svg
 var alignbottomleft_default = (function buildSVG12(parent) {
   const builder = new DOMBuilder(parent);
   builder.openTag("svg", { "width": "20", "height": "20", "viewBox": "0 0 20 20", "fill": "none", "stroke": "currentColor" }, void 0, "http://www.w3.org/2000/svg");
@@ -1058,6 +1058,7 @@ var AbleDOM = class {
     __publicField(this, "_idleResolve");
     __publicField(this, "_currentAnchoredIssues", /* @__PURE__ */ new Map());
     __publicField(this, "_currentNotAnchoredIssues", []);
+    __publicField(this, "_readIssues", /* @__PURE__ */ new Set());
     __publicField(this, "_getHighlighter", () => {
       if (!this._elementHighlighter && !this._isDisposed) {
         this._elementHighlighter = new ElementHighlighter(this._win);
@@ -1099,6 +1100,9 @@ var AbleDOM = class {
       ((_c = (_b = this._win) == null ? void 0 : _b.console) == null ? void 0 : _c.error)) == null ? void 0 : _d.apply(null, args);
     });
     this._win = win;
+    if (props.exposeInstanceForTesting) {
+      this._win.ableDOMInstanceForTesting = this;
+    }
     this._props = props;
     const _elementsToValidate = /* @__PURE__ */ new Set();
     const _elementsToRemove = /* @__PURE__ */ new Set();
@@ -1414,29 +1418,60 @@ var AbleDOM = class {
       rules.forEach((rule) => this._removeIssue(element, rule));
     });
   }
-  _getCurrentIssues() {
-    const issues = this._currentNotAnchoredIssues.slice(0);
+  _getCurrentIssues(markAsRead) {
+    const issues = [];
+    this._currentNotAnchoredIssues.forEach((issue) => {
+      if (!this._readIssues.has(issue)) {
+        issues.push(issue);
+      }
+      if (markAsRead) {
+        this._readIssues.add(issue);
+      }
+    });
     this._currentAnchoredIssues.forEach((issueByRule) => {
       issueByRule.forEach((issue) => {
-        issues.push(issue);
+        if (!this._readIssues.has(issue)) {
+          issues.push(issue);
+        }
+        if (markAsRead) {
+          this._readIssues.add(issue);
+        }
       });
     });
     return issues;
   }
-  idle() {
+  idle(markAsRead, timeout) {
     if (!this._clearValidationTimeout) {
-      return Promise.resolve(this._getCurrentIssues());
-    }
+      return Promise.resolve(this._getCurrentIssues(!!markAsRead));
+    }
+    let timeoutClear;
+    let timeoutResolve;
+    let timeoutPromise = timeout ? new Promise((resolve) => {
+      timeoutResolve = () => {
+        timeoutClear == null ? void 0 : timeoutClear();
+        timeoutResolve = void 0;
+        resolve(null);
+      };
+      let timeoutTimer = this._win.setTimeout(() => {
+        timeoutClear = void 0;
+        timeoutResolve == null ? void 0 : timeoutResolve();
+      }, timeout);
+      timeoutClear = () => {
+        this._win.clearTimeout(timeoutTimer);
+        timeoutClear = void 0;
+      };
+    }) : void 0;
     if (!this._idlePromise) {
       this._idlePromise = new Promise((resolve) => {
         this._idleResolve = () => {
           delete this._idlePromise;
           delete this._idleResolve;
-          resolve(this._getCurrentIssues());
+          resolve(this._getCurrentIssues(!!markAsRead));
+          timeoutResolve == null ? void 0 : timeoutResolve();
         };
       });
     }
-    return this._idlePromise;
+    return timeoutPromise ? Promise.race([this._idlePromise, timeoutPromise]) : this._idlePromise;
   }
   clearCurrentIssues(anchored = true, notAnchored = true) {
     if (anchored) {