feat: deprecate and replace dom.isVisible, utils.isHidden, and dom.isHiddenWithCss

lib/checks/navigation/heading-order-evaluate.js

@@ -54,8 +54,10 @@ function headingOrderEvaluate() {
   // @see https://github.com/dequelabs/axe-core/issues/728
   const selector = 'h1, h2, h3, h4, h5, h6, [role=heading], iframe, frame';
   // TODO: es-modules_tree
-  const vNodes = querySelectorAllFilter(axe._tree[0], selector, vNode =>
-    isVisibleForScreenreader(vNode.actualNode)
+  const vNodes = querySelectorAllFilter(
+    axe._tree[0],
+    selector,
+    isVisibleForScreenreader
   );
 
   headingOrder = vNodes.map(vNode => {

lib/commons/dom/has-lang-text.js

@@ -1,6 +1,6 @@
 import { hasChildTextNodes } from './has-content-virtual';
 import isVisualContent from './is-visual-content';
-import isVisibleForScreenreader from './is-visible-for-screenreader';
+import isHiddenForEveryone from './is-hidden-for-everyone';
 
 /**
  * Check that a node has text, or an accessible name which language is defined by the
@@ -19,9 +19,10 @@ export default function hasLangText(virtualNode) {
     // See: https://github.com/dequelabs/axe-core/issues/3281
     return !!axe.commons.text.accessibleTextVirtual(virtualNode);
   }
-  return virtualNode.children.some(child => (
-    !child.attr('lang') && // non-empty lang
-    hasLangText(child) && // has text
-    isVisibleForScreenreader(child) // Not hidden for AT
-  ));
+  return virtualNode.children.some(
+    child =>
+      !child.attr('lang') && // non-empty lang
+      hasLangText(child) && // has text
+      !isHiddenForEveryone(child) // Not hidden for anyone
+  );
 }

lib/commons/dom/is-hidden-for-everyone.js

@@ -5,44 +5,55 @@ import {
   nativelyHidden,
   displayHidden,
   visibilityHidden
-} from './visibility-functions';
+} from './visibility-methods';
+
+const hiddenMethods = [displayHidden, visibilityHidden];
 
 /**
  * Determine if an element is hidden from screenreaders and visual users
  * @method isHiddenForEveryone
  * @memberof axe.commons.dom
  * @param {VirtualNode} vNode The Virtual Node
- * @param {Boolean} [ancestors=true] If the ancestor tree should be used
- * @param {Boolean} recursed
+ * @param {Object} [options]
+ * @param {Boolean} [options.skipAncestors] If the ancestor tree should be not be used
+ * @param {Boolean} [options.isAncestor] If this function is being called on an ancestor for the target node
  * @return {Boolean} The element's visibility state
  */
-export default function isHiddenForEveryone(vNode, ancestors = true, recursed) {
+export default function isHiddenForEveryone(
+  vNode,
+  { skipAncestors, isAncestor } = {}
+) {
   vNode = vNode instanceof AbstractVirtualNode ? vNode : getNodeFromTree(vNode);
 
-  return ancestors
-    ? isHiddenAncestors(vNode, recursed)
-    : isHiddenSelf(vNode, recursed);
+  if (skipAncestors) {
+    return isHiddenSelf(vNode, { isAncestor });
+  }
+
+  return isHiddenAncestors(vNode, { isAncestor });
 }
 
 /**
  * Check the element for visibility state
  */
-const isHiddenSelf = memoize(function isHiddenSelfMemoized(vNode, recursed) {
+const isHiddenSelf = memoize(function isHiddenSelfMemoized(
+  vNode,
+  { isAncestor }
+) {
   if (nativelyHidden(vNode)) {
     return true;
   }
 
-  if (vNode.actualNode) {
-    const hiddenMethods = [displayHidden, visibilityHidden];
+  if (!vNode.actualNode) {
+    return false;
+  }
 
-    if (hiddenMethods.some(method => method(vNode, recursed))) {
-      return true;
-    }
+  if (hiddenMethods.some(method => method(vNode, { isAncestor }))) {
+    return true;
+  }
 
-    // detached node
-    if (!vNode.actualNode.isConnected) {
-      return true;
-    }
+  // detached node
+  if (!vNode.actualNode.isConnected) {
+    return true;
   }
 
   return false;
@@ -53,15 +64,15 @@ const isHiddenSelf = memoize(function isHiddenSelfMemoized(vNode, recursed) {
  */
 const isHiddenAncestors = memoize(function isHiddenAncestorsMemoized(
   vNode,
-  recursed
+  { isAncestor }
 ) {
-  if (isHiddenSelf(vNode, recursed)) {
+  if (isHiddenSelf(vNode, { isAncestor })) {
     return true;
   }
 
-  if (vNode.parent) {
-    return isHiddenAncestors(vNode.parent, true);
+  if (!vNode.parent) {
+    return false;
   }
 
-  return false;
+  return isHiddenAncestors(vNode.parent, { isAncestor: true });
 });

lib/commons/dom/is-modal-open.js

@@ -42,7 +42,7 @@ function isModalOpen(options) {
     // TODO: es-module-_tree
     axe._tree[0],
     'dialog, [role=dialog], [aria-modal=true]',
-    vNode => isVisibleOnScreen(vNode)
+    isVisibleOnScreen
   );
 
   if (definiteModals.length) {

lib/commons/dom/is-offscreen.js

@@ -1,6 +1,7 @@
 import getComposedParent from './get-composed-parent';
 import getElementCoordinates from './get-element-coordinates';
 import getViewportSize from './get-viewport-size';
+import AbstractVirtualNode from '../../core/base/virtual-node/abstract-virtual-node';
 
 function noParentScrolled(element, offset) {
   element = getComposedParent(element);
@@ -22,14 +23,17 @@ function noParentScrolled(element, offset) {
  * @memberof axe.commons.dom
  * @instance
  * @param  {Element} element
+ * @param {Object} [options]
+ * @param {Boolean} [options.isAncestor] If this function is being called on an ancestor of the target node
  * @return {Boolean}
  */
-function isOffscreen(element, recursed) {
-  if (recursed) {
+function isOffscreen(element, { isAncestor } = {}) {
+  if (isAncestor) {
     return false;
   }
 
-  element = element.actualNode ? element.actualNode : element
+  element =
+    element instanceof AbstractVirtualNode ? element.actualNode : element;
 
   let leftBoundary;
   const docElement = document.documentElement;

lib/commons/dom/is-visible-for-screenreader.js

@@ -2,7 +2,7 @@ import AbstractVirtualNode from '../../core/base/virtual-node/abstract-virtual-n
 import { getNodeFromTree } from '../../core/utils';
 import memoize from '../../core/utils/memoize';
 import isHiddenForEveryone from './is-hidden-for-everyone';
-import { ariaHidden, isAreaVisible } from './visibility-functions';
+import { ariaHidden, isAreaHidden } from './visibility-methods';
 
 /**
  * Determine if an element is visible to a screen reader
@@ -13,30 +13,37 @@ import { ariaHidden, isAreaVisible } from './visibility-functions';
  */
 export default function isVisibleForScreenreader(vNode) {
   vNode = vNode instanceof AbstractVirtualNode ? vNode : getNodeFromTree(vNode);
-  return isVisibleForScreenreaderVirtual(vNode);
+  return isVisibleForScreenreaderVirtual(vNode, {});
 }
 
 /**
  * Check the element and ancestors
  */
 const isVisibleForScreenreaderVirtual = memoize(
-  function isVisibleForScreenreaderMemoized(vNode, recursed) {
+  function isVisibleForScreenreaderMemoized(vNode, options) {
+    // cannot use memoize with a default parameter if we transpile
+    // the code. the transpiler removes the parameter from the function
+    // signature so the function is only memoized with the one
+    // parameter
+    options = options ?? {};
+    const isAncestor = options.isAncestor;
+
     if (ariaHidden(vNode)) {
       return false;
     }
 
     if (vNode.actualNode && vNode.props.nodeName === 'area') {
-      return isAreaVisible(vNode, isVisibleForScreenreaderVirtual);
+      return !isAreaHidden(vNode, isVisibleForScreenreaderVirtual);
     }
 
-    if (isHiddenForEveryone(vNode, false, recursed)) {
+    if (isHiddenForEveryone(vNode, { skipAncestors: true, isAncestor })) {
       return false;
     }
 
-    if (vNode.parent) {
-      return isVisibleForScreenreaderVirtual(vNode.parent, true);
+    if (!vNode.parent) {
+      return true;
     }
 
-    return true;
+    return isVisibleForScreenreaderVirtual(vNode.parent, { isAncestor: true });
   }
 );

lib/commons/dom/is-visible-on-screen.js

@@ -7,10 +7,18 @@ import {
   scrollClipped,
   overflowHidden,
   clipHidden,
-  isAreaVisible
-} from './visibility-functions';
+  isAreaHidden
+} from './visibility-methods';
 import isOffscreen from './is-offscreen';
 
+const hiddenMethods = [
+  opacityHidden,
+  scrollClipped,
+  overflowHidden,
+  clipHidden,
+  isOffscreen
+];
+
 /**
  * Determine if an element is visible on screen
  * @method isVisibleOnScreen
@@ -25,33 +33,33 @@ export default function isVisibleOnScreen(vNode) {
 
 const isVisibleOnScreenVirtual = memoize(function isVisibleOnScreenMemoized(
   vNode,
-  recursed
+  options
 ) {
+  // cannot use memoize with a default parameter if we transpile
+  // the code. the transpiler removes the parameter from the function
+  // signature so the function is only memoized with the one
+  // parameter
+  options = options ?? {};
+  const isAncestor = options.isAncestor;
+
   if (vNode.actualNode && vNode.props.nodeName === 'area') {
-    return isAreaVisible(vNode, isVisibleOnScreenVirtual);
+    return !isAreaHidden(vNode, isVisibleOnScreenVirtual);
   }
 
-  if (isHiddenForEveryone(vNode, false, recursed)) {
+  if (isHiddenForEveryone(vNode, { skipAncestors: true, isAncestor })) {
     return false;
   }
 
-  if (vNode.actualNode) {
-    const hiddenMethods = [
-      opacityHidden,
-      scrollClipped,
-      overflowHidden,
-      clipHidden,
-      isOffscreen
-    ];
-
-    if (hiddenMethods.some(method => method(vNode, recursed))) {
-      return false;
-    }
+  if (
+    vNode.actualNode &&
+    hiddenMethods.some(method => method(vNode, { isAncestor }))
+  ) {
+    return false;
   }
 
-  if (vNode.parent) {
-    return isVisibleOnScreenVirtual(vNode.parent, true);
+  if (!vNode.parent) {
+    return true;
   }
 
-  return true;
+  return isVisibleOnScreenVirtual(vNode.parent, { isAncestor: true });
 });