refactor: put isContext methods on axe.utils (#4524)

Had a couple scenarios where this code was getting copied over to other
repos. For backward compat reasons that's going to need to stay, but at
least if we have these methods on axe.utils we can prevent problems in
the future if we change how context works.

No QA needed on this one.

axe.d.ts

@@ -70,16 +70,19 @@ declare namespace axe {
     | LabelledShadowDomSelector
     | LabelledFramesSelector;
   type SelectorList = Array<Selector | FramesSelector> | NodeList;
+  type ContextProp = Selector | SelectorList;
   type ContextObject =
     | {
-        include: Selector | SelectorList;
-        exclude?: Selector | SelectorList;
+        include: ContextProp;
+        exclude?: ContextProp;
       }
     | {
-        exclude: Selector | SelectorList;
-        include?: Selector | SelectorList;
+        exclude: ContextProp;
+        include?: ContextProp;
       };
-  type ElementContext = Selector | SelectorList | ContextObject;
+  type ContextSpec = ContextProp | ContextObject;
+  /** Synonym to ContextSpec */
+  type ElementContext = ContextSpec;
 
   type SerialSelector =
     | BaseSelector
@@ -406,6 +409,16 @@ declare namespace axe {
     shadowSelect: (selector: CrossTreeSelector) => Element | null;
     shadowSelectAll: (selector: CrossTreeSelector) => Element[];
     getStandards(): Required<Standards>;
+    isContextSpec: (context: unknown) => context is ContextSpec;
+    isContextObject: (context: unknown) => context is ContextObject;
+    isContextProp: (context: unknown) => context is ContextProp;
+    isLabelledFramesSelector: (
+      selector: unknown
+    ) => selector is LabelledFramesSelector;
+    isLabelledShadowDomSelector: (
+      selector: unknown
+    ) => selector is LabelledShadowDomSelector;
+
     DqElement: new (
       elm: Element,
       options?: { absolutePaths?: boolean }

lib/core/base/context/normalize-context.js

@@ -1,4 +1,12 @@
-import { assert as utilsAssert } from '../../utils';
+import {
+  assert as utilsAssert,
+  objectHasOwn,
+  isArrayLike,
+  isContextObject,
+  isContextProp,
+  isLabelledFramesSelector,
+  isLabelledShadowDomSelector
+} from '../../utils';
 
 /**
  * Normalize the input of "context" so that many different methods of input are accepted
@@ -29,16 +37,6 @@ export function normalizeContext(contextSpec) {
   return { include, exclude };
 }
 
-/**
- * Determine if some value can be parsed as a context
- * @private
- * @param  {Mixed} contextSpec The configuration object passed to `Context`
- * @return {boolea}
- */
-export function isContextSpec(contextSpec) {
-  return isContextObject(contextSpec) || isContextProp(contextSpec);
-}
-
 function normalizeContextList(selectorList = []) {
   const normalizedList = [];
   if (!isArrayLike(selectorList)) {
@@ -89,30 +87,6 @@ function normalizeFrameSelectors(frameSelectors) {
   return normalizedSelectors;
 }
 
-function isContextObject(contextSpec) {
-  return ['include', 'exclude'].some(
-    prop => objectHasOwn(contextSpec, prop) && isContextProp(contextSpec[prop])
-  );
-}
-
-function isContextProp(contextList) {
-  return (
-    typeof contextList === 'string' ||
-    contextList instanceof window.Node ||
-    isLabelledFramesSelector(contextList) ||
-    isLabelledShadowDomSelector(contextList) ||
-    isArrayLike(contextList)
-  );
-}
-
-function isLabelledFramesSelector(selector) {
-  return objectHasOwn(selector, 'fromFrames');
-}
-
-function isLabelledShadowDomSelector(selector) {
-  return objectHasOwn(selector, 'fromShadowDom');
-}
-
 function assertLabelledFrameSelector(selector) {
   assert(
     Array.isArray(selector.fromFrames),
@@ -157,28 +131,10 @@ function isShadowSelector(selector) {
   );
 }
 
-function isArrayLike(arr) {
-  return (
-    // Avoid DOM weirdness
-    arr &&
-    typeof arr === 'object' &&
-    typeof arr.length === 'number' &&
-    arr instanceof window.Node === false
-  );
-}
-
 // Wrapper to ensure the correct message
 function assert(bool, str) {
   utilsAssert(
     bool,
     `Invalid context; ${str}\nSee: https://github.com/dequelabs/axe-core/blob/master/doc/context.md`
   );
 }
-
-// Wrapper to prevent throwing for non-objects & null
-function objectHasOwn(obj, prop) {
-  if (!obj || typeof obj !== 'object') {
-    return false;
-  }
-  return Object.prototype.hasOwnProperty.call(obj, prop);
-}

lib/core/public/run/normalize-run-params.js

@@ -1,5 +1,4 @@
-import { clone } from '../../utils';
-import { isContextSpec } from '../../base/context/normalize-context';
+import { clone, isContextSpec } from '../../utils';
 
 /**
  * Normalize the optional params of axe.run()

lib/core/utils/index.js

@@ -43,6 +43,14 @@ export { default as getStyleSheetFactory } from './get-stylesheet-factory';
 export { default as getXpath } from './get-xpath';
 export { default as getAncestry } from './get-ancestry';
 export { default as injectStyle } from './inject-style';
+export { default as isArrayLike } from './is-array-like';
+export {
+  isContextSpec,
+  isContextObject,
+  isContextProp,
+  isLabelledShadowDomSelector,
+  isLabelledFramesSelector
+} from './is-context';
 export { default as isHidden } from './is-hidden';
 export { default as isHtmlElement } from './is-html-element';
 export { default as isNodeInContext } from './is-node-in-context';
@@ -59,6 +67,7 @@ export { default as mergeResults } from './merge-results';
 export { default as nodeSerializer } from './node-serializer';
 export { default as nodeSorter } from './node-sorter';
 export { default as nodeLookup } from './node-lookup';
+export { default as objectHasOwn } from './object-has-own';
 export { default as parseCrossOriginStylesheet } from './parse-crossorigin-stylesheet';
 export { default as parseSameOriginStylesheet } from './parse-sameorigin-stylesheet';
 export { default as parseStylesheet } from './parse-stylesheet';

lib/core/utils/is-array-like.js

@@ -0,0 +1,15 @@
+/**
+ * Checks if a value is array-like.
+ *
+ * @param {any} arr - The value to check.
+ * @returns {boolean} - Returns true if the value is array-like, false otherwise.
+ */
+export default function isArrayLike(arr) {
+  return (
+    !!arr &&
+    typeof arr === 'object' &&
+    typeof arr.length === 'number' &&
+    // Avoid DOM weirdness
+    arr instanceof window.Node === false
+  );
+}

lib/core/utils/is-context.js

@@ -0,0 +1,53 @@
+import objectHasOwn from './object-has-own';
+import isArrayLike from './is-array-like';
+
+/**
+ * Determine if some value can be parsed as a context
+ * @private
+ * @param  {Mixed} contextSpec The configuration object passed to `Context`
+ * @return {boolea}
+ */
+export function isContextSpec(contextSpec) {
+  return isContextObject(contextSpec) || isContextProp(contextSpec);
+}
+
+/**
+ * Checks if the given context specification is a valid context object.
+ *
+ * @param {Object} contextSpec - The context specification object to check.
+ * @returns {boolean} - Returns true if the context specification is a valid context object, otherwise returns false.
+ */
+export function isContextObject(contextSpec) {
+  return ['include', 'exclude'].some(
+    prop => objectHasOwn(contextSpec, prop) && isContextProp(contextSpec[prop])
+  );
+}
+
+/**
+ * Checks if the given contextList is a valid context property.
+ * @param {string|Node|Array} contextList - The contextList to check.
+ * @returns {boolean} - Returns true if the contextList is a valid context property, otherwise false.
+ */
+export function isContextProp(contextList) {
+  return (
+    typeof contextList === 'string' ||
+    contextList instanceof window.Node ||
+    isLabelledFramesSelector(contextList) ||
+    isLabelledShadowDomSelector(contextList) ||
+    isArrayLike(contextList)
+  );
+}
+
+export function isLabelledFramesSelector(selector) {
+  // This doesn't guarantee the selector is valid.
+  // Just that this isn't a runOptions object
+  // Normalization will ignore invalid selectors
+  return objectHasOwn(selector, 'fromFrames');
+}
+
+export function isLabelledShadowDomSelector(selector) {
+  // This doesn't guarantee the selector is valid.
+  // Just that this isn't a runOptions object
+  // Normalization will ignore invalid selectors
+  return objectHasOwn(selector, 'fromShadowDom');
+}

lib/core/utils/object-has-own.js

@@ -0,0 +1,7 @@
+// Wrapper to prevent throwing for non-objects & null
+export default function objectHasOwn(obj, prop) {
+  if (!obj || typeof obj !== 'object') {
+    return false;
+  }
+  return Object.prototype.hasOwnProperty.call(obj, prop);
+}

test/core/utils/is-array-like.js

@@ -0,0 +1,30 @@
+describe('axe.utils.isArrayLike', () => {
+  const isArrayLike = axe.utils.isArrayLike;
+
+  it('is true for an array', () => {
+    assert.isTrue(isArrayLike([]));
+  });
+
+  it('is true for an array-like object', () => {
+    assert.isTrue(isArrayLike({ length: 1 }));
+  });
+
+  it('is false for strings (which also have .length)', () => {
+    assert.isFalse(isArrayLike('string'));
+  });
+
+  it('is false for a Node with .length', () => {
+    const div = document.createElement('div');
+    div.length = 123;
+    assert.isFalse(isArrayLike(div));
+  });
+
+  it('is false for non-array-like objects', () => {
+    assert.isFalse(isArrayLike({}));
+    assert.isFalse(isArrayLike(null));
+    assert.isFalse(isArrayLike(undefined));
+    assert.isFalse(isArrayLike(1));
+    assert.isFalse(isArrayLike(true));
+    assert.isFalse(isArrayLike(false));
+  });
+});