From ef0c595b5b5fe63657849974959ecb1360e3a181 Mon Sep 17 00:00:00 2001
From: Charley <cpugmire@hubspot.com>
Date: Fri, 12 Sep 2025 18:10:28 -0500
Subject: [PATCH 1/2] quick attempt at `checkVisibility` API

---
 src/__tests__/role-helpers.js | 74 ++++++++++++++++++++++++++++++++++-
 src/role-helpers.js           | 36 +++++++++++++++++
 2 files changed, 109 insertions(+), 1 deletion(-)

diff --git a/src/__tests__/role-helpers.js b/src/__tests__/role-helpers.js
index f47daa42..0eb54577 100644
--- a/src/__tests__/role-helpers.js
+++ b/src/__tests__/role-helpers.js
@@ -4,6 +4,7 @@ import {
   logRoles,
   getImplicitAriaRoles,
   isInaccessible,
+  isSubtreeInaccessible,
 } from '../role-helpers'
 import {render} from './helpers/test-utils'
 
@@ -25,7 +26,7 @@ function setup() {
   <a data-testid="invalid-link">invalid link</a>
 
   <nav data-testid='a-nav' />
-  
+
   <h1 data-testid='a-h1'>Main Heading</h1>
   <h2 data-testid='a-h2'>Sub Heading</h2>
   <h3 data-testid='a-h3'>Tertiary Heading</h3>
@@ -211,3 +212,74 @@ test.each([
 
   expect(isInaccessible(container.querySelector('button'))).toBe(expected)
 })
+
+describe('checkVisibility API integration', () => {
+  let originalCheckVisibility
+
+  beforeEach(() => {
+    // This may not exist depending on the environment
+    originalCheckVisibility = Element.prototype.checkVisibility
+  })
+
+  afterEach(() => {
+    if (originalCheckVisibility) {
+      Element.prototype.checkVisibility = originalCheckVisibility
+    } else {
+      delete Element.prototype.checkVisibility
+    }
+  })
+
+  test('uses checkVisibility when available', () => {
+    const mockCheckVisibility = jest.fn().mockReturnValue(false)
+    Element.prototype.checkVisibility = mockCheckVisibility
+
+    const {container} = render('<div><button>Test</button></div>')
+    const button = container.querySelector('button')
+
+    const result = isSubtreeInaccessible(button)
+
+    expect(mockCheckVisibility).toHaveBeenCalledWith({
+      visibilityProperty: true,
+      opacityProperty: false,
+    })
+    expect(result).toBe(true)
+  })
+
+  test('falls back to getComputedStyle when checkVisibility unavailable', () => {
+    // Remove checkVisibility to test fallback
+    delete Element.prototype.checkVisibility
+
+    const {container} = render('<button style="display: none;">Test</button>')
+    const button = container.querySelector('button')
+
+    expect(isSubtreeInaccessible(button)).toBe(true)
+  })
+
+  test('checkVisibility and fallback produce same results', () => {
+    const testCases = [
+      '<div><button>Visible</button></div>',
+      '<div style="display: none;"><button>Hidden</button></div>',
+      '<div style="visibility: hidden;"><button>Hidden</button></div>',
+      '<div hidden><button>Hidden</button></div>',
+      '<div aria-hidden="true"><button>Hidden</button></div>',
+    ]
+
+    testCases.forEach(html => {
+      const {container: container1} = render(html)
+      const button1 = container1.querySelector('button')
+
+      const resultWithAPI = isInaccessible(button1)
+
+      delete Element.prototype.checkVisibility
+      const {container: container2} = render(html)
+      const button2 = container2.querySelector('button')
+      const resultWithoutAPI = isInaccessible(button2)
+
+      expect(resultWithAPI).toBe(resultWithoutAPI)
+
+      if (originalCheckVisibility) {
+        Element.prototype.checkVisibility = originalCheckVisibility
+      }
+    })
+  })
+})
diff --git a/src/role-helpers.js b/src/role-helpers.js
index 8d7e7cb0..d1b55a8d 100644
--- a/src/role-helpers.js
+++ b/src/role-helpers.js
@@ -8,6 +8,17 @@ import {getConfig} from './config'
 
 const elementRoleList = buildElementRoleList(elementRoles)
 
+const checkVisibilityOptions = {
+  visibilityProperty: true,
+  opacityProperty: false,
+}
+
+function supportsCheckVisibility() {
+  return (
+    typeof Element !== 'undefined' && 'checkVisibility' in Element.prototype
+  )
+}
+
 /**
  * @param {Element} element -
  * @returns {boolean} - `true` if `element` and its subtree are inaccessible
@@ -21,6 +32,10 @@ function isSubtreeInaccessible(element) {
     return true
   }
 
+  if (supportsCheckVisibility()) {
+    return !element.checkVisibility(checkVisibilityOptions)
+  }
+
   const window = element.ownerDocument.defaultView
   if (window.getComputedStyle(element).display === 'none') {
     return true
@@ -47,6 +62,27 @@ function isInaccessible(element, options = {}) {
   const {
     isSubtreeInaccessible: isSubtreeInaccessibleImpl = isSubtreeInaccessible,
   } = options
+
+  if (supportsCheckVisibility()) {
+    if (!element.checkVisibility(checkVisibilityOptions)) {
+      return true
+    }
+
+    // Still need to walk up the tree for aria-hidden and hidden attributes
+    let currentElement = element
+    while (currentElement) {
+      if (
+        currentElement.hidden === true ||
+        currentElement.getAttribute('aria-hidden') === 'true'
+      ) {
+        return true
+      }
+      currentElement = currentElement.parentElement
+    }
+
+    return false
+  }
+
   const window = element.ownerDocument.defaultView
   // since visibility is inherited we can exit early
   if (window.getComputedStyle(element).visibility === 'hidden') {

From f1c95fb40ffd396ef0f6e770350f98f4a9c1c617 Mon Sep 17 00:00:00 2001
From: Charley <cpugmire@hubspot.com>
Date: Tue, 16 Sep 2025 17:40:05 -0500
Subject: [PATCH 2/2] test env

---
 src/__tests__/role-helpers.js | 18 +-----------------
 1 file changed, 1 insertion(+), 17 deletions(-)

diff --git a/src/__tests__/role-helpers.js b/src/__tests__/role-helpers.js
index 0eb54577..e8714f4f 100644
--- a/src/__tests__/role-helpers.js
+++ b/src/__tests__/role-helpers.js
@@ -214,17 +214,8 @@ test.each([
 })
 
 describe('checkVisibility API integration', () => {
-  let originalCheckVisibility
-
   beforeEach(() => {
-    // This may not exist depending on the environment
-    originalCheckVisibility = Element.prototype.checkVisibility
-  })
-
-  afterEach(() => {
-    if (originalCheckVisibility) {
-      Element.prototype.checkVisibility = originalCheckVisibility
-    } else {
+    if (Element.prototype.checkVisibility) {
       delete Element.prototype.checkVisibility
     }
   })
@@ -246,9 +237,6 @@ describe('checkVisibility API integration', () => {
   })
 
   test('falls back to getComputedStyle when checkVisibility unavailable', () => {
-    // Remove checkVisibility to test fallback
-    delete Element.prototype.checkVisibility
-
     const {container} = render('<button style="display: none;">Test</button>')
     const button = container.querySelector('button')
 
@@ -276,10 +264,6 @@ describe('checkVisibility API integration', () => {
       const resultWithoutAPI = isInaccessible(button2)
 
       expect(resultWithAPI).toBe(resultWithoutAPI)
-
-      if (originalCheckVisibility) {
-        Element.prototype.checkVisibility = originalCheckVisibility
-      }
     })
   })
 })