interactive-supports-focus

Author: kddnewton

README.md

@@ -59,7 +59,7 @@ I'm currently working on getting parity between this project and `eslint-plugin-
 - [x] form-control-has-label
 - [x] heading-has-content
 - [x] iframe-has-title
-- [ ] interactive-supports-focus
+- [x] interactive-supports-focus
 - [ ] label-has-for
 - [x] media-has-caption
 - [x] mouse-events-have-key-events

docs/rules/interactive-supports-focus.md

@@ -0,0 +1,89 @@
+# interactive-supports-focus
+
+Elements with an interactive role and interaction handlers (mouse or key press) must be focusable.
+
+## How do I resolve this error?
+
+### Case: I got the error "Elements with the '\${role}' interactive role must be tabbable". How can I fix this?
+
+This element is a stand-alone control like a button, a link or a form element. A user should be able to reach this element by pressing the tab key on their keyboard.
+
+Replace the component with one that renders semantic html element like `<button>`, `<a href>` or `<input>`. Generally buttons, links and form elements should be reachable via tab key presses. An element that can be tabbed to is said to be in the _tab ring_.
+
+-- or --
+
+Add the `tabindex` property to your component. A value of zero indicates that this element can be tabbed to.
+
+```
+<div role="button" @click="foo" tabindex="0" />
+```
+
+### Case: I got the error "Elements with the '\${role}' interactive role must be focusable". How can I fix this?
+
+This element is part of a group of buttons, links, menu items, etc. Or this element is part of a composite widget. Composite widgets prescribe standard [keyboard interaction patterns](https://www.w3.org/TR/wai-aria-practices-1.1/#kbd_generalnav). Within a group of similar elements -- like a button bar -- or within a composite widget, elements that can be focused are given a tabindex of -1. This makes the element _focusable_ but not _tabbable_. Generally one item in a group should have a tabindex of zero so that a user can tab to the component. Once an element in the component has focus, your key management behaviors will control traversal within the component's pieces. As the UI author, you will need to implement the key handling behaviors such as listening for traversal key (up/down/left/right) presses and moving the page focus between the focusable elements in your widget.
+
+```
+<div role="menu">
+  <div role="menuitem" tabindex="0">Open</div>
+  <div role="menuitem" tabindex="-1">Save</div>
+  <div role="menuitem" tabindex="-1">Close</div>
+</div>
+```
+
+In the example above, the first item in the group can be tabbed to. The developer provides the ability to traverse to the subsequent items via the up/down/left/right arrow keys. Traversing via arrow keys is not provided by the browser or the assistive technology. See [Fundamental Keyboard Navigation Conventions](https://www.w3.org/TR/wai-aria-practices-1.1/#kbd_generalnav) for information about established traversal behaviors for various UI widgets.
+
+_References:_
+
+1. [AX_FOCUS_02](https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules#ax_focus_02)
+2. [Mozilla Developer Network - ARIA Techniques](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_button_role#Keyboard_and_focus)
+3. [Fundamental Keyboard Navigation Conventions](https://www.w3.org/TR/wai-aria-practices-1.1/#kbd_generalnav)
+4. [WAI-ARIA Authoring Practices Guide - Design Patterns and Widgets](https://www.w3.org/TR/wai-aria-practices-1.1/#aria_ex)
+
+## Rule details
+
+This rule takes an options object with the key `tabbable`. The value is an array of interactive ARIA roles that should be considered tabbable, not just focusable. Any interactive role not included in this list will be flagged as needing to be focusable (tabindex of -1).
+
+```json
+{
+  "vue-accessibility/interactive-supports-focus": ["error", {
+    "tabbable": [
+      "button",
+      "checkbox",
+      "link",
+      "searchbox",
+      "spinbutton",
+      "switch",
+      "textbox"
+    ]
+  }
+]
+```
+
+### Succeed
+
+```vue
+<!-- Good: div with @click attribute is hidden from screen reader -->
+<div aria-hidden @click="() => void 0" />
+
+<!-- Good: span with @click attribute is in the tab order -->
+<span @click="doSomething" tabindex="0" role="button">Click me!</span>
+
+<!-- Good: span with @click attribute may be focused programmatically -->
+<span @click="doSomething" tabindex="-1" role="menuitem">Click me too!</span>
+
+<!-- Good: anchor element with href is inherently focusable -->
+<a href="javascript:void(0)" @click="doSomething">Click ALL the things!</a>
+
+<!-- Good: buttons are inherently focusable -->
+<button @click="doSomething">Click the button</button>
+```
+
+### Fail
+
+```vue
+<!-- Bad: span with @click attribute has no tabindex -->
+<span @click="submitForm" role="button">Submit</span>
+
+<!-- Bad: anchor element without href is not focusable -->
+<a @click="showNextPage" role="button">Next page</a>
+```

src/index.js

@@ -9,6 +9,7 @@ module.exports = {
     "form-control-has-label": require("./rules/form-control-has-label"),
     "heading-has-content": require("./rules/heading-has-content"),
     "iframe-has-title": require("./rules/iframe-has-title"),
+    "interactive-supports-focus": require("./rules/interactive-supports-focus"),
     "media-has-caption": require("./rules/media-has-caption"),
     "mouse-events-have-key-events": require("./rules/mouse-events-have-key-events"),
     "no-access-key": require("./rules/no-access-key"),
@@ -38,6 +39,20 @@ module.exports = {
         "vue-accessibility/form-control-has-label": "error",
         "vue-accessibility/heading-has-content": "error",
         "vue-accessibility/iframe-has-title": "error",
+        "vue-accessibility/interactive-supports-focus": [
+          "error",
+          {
+            tabbable: [
+              "button",
+              "checkbox",
+              "link",
+              "searchbox",
+              "spinbutton",
+              "switch",
+              "textbox"
+            ]
+          }
+        ],
         "vue-accessibility/media-has-caption": "error",
         "vue-accessibility/mouse-events-have-key-events": "error",
         "vue-accessibility/no-access-key": "error",

src/rules/__tests__/interactive-supports-focus.test.js

@@ -0,0 +1,81 @@
+const rule = require("../interactive-supports-focus");
+const makeRuleTester = require("./makeRuleTester");
+
+makeRuleTester("interactive-supports-focus", rule, {
+  valid: [
+    "<div />",
+    "<div aria-hidden @click='void 0' />",
+    "<div aria-hidden='true' @click='void 0' />",
+    "<div aria-hidden='hidden !== false' @click='void 0' />",
+    "<div aria-hidden='1 < 2' @click='void 0' />",
+    "<div aria-hidden='1 <= 2' @click='void 0' />",
+    "<div @click='void 0' />",
+    "<div @click='void 0' :tabindex='undefined' />",
+    "<div @click='void 0' tabindex='bad' />",
+    "<div @click='void 0' :role='undefined' />",
+    "<div role='section' @click='void 0' />",
+    "<div @click='void 0' :aria-hidden='false' />",
+    "<input type='text' @click='void 0' />",
+    "<input type='hidden' @click='void 0' tabindex='-1' />",
+    "<input type='hidden' @click='void 0' :tabindex='-1' />",
+    "<input @click='void 0' />",
+    "<input @click='void 0' role='combobox' />",
+    "<button @click='void 0' class='foo' />",
+    "<option @click='void 0' class='foo' />",
+    "<select @click='void 0' class='foo' />",
+    "<area href='#' @click='void 0' class='foo' />",
+    "<area @click='void 0' class='foo' />",
+    "<textarea @click='void 0' class='foo' />",
+    "<a @click='showNextPage'>Next page</a>",
+    "<a @click='showNextPage' :tabindex='undefined'>Next page</a>",
+    "<a @click='showNextPage()' tabindex='bad'>Next page</a>",
+    "<a @click='void 0' />",
+    "<a tabindex='0' @click='void 0' />",
+    "<a :tabindex='dynamicTabIndex' @click='void 0' />",
+    "<a :tabindex='0' @click='void 0' />",
+    "<a role='button' href='#' @click='void 0' />",
+    "<a @click='void 0' href='http://x.y.z' />",
+    "<a @click='void 0' href='http://x.y.z' tabindex='0' />",
+    "<a @click='void 0' href='http://x.y.z' :tabindex='0' />",
+    "<a @click='void 0' href='http://x.y.z' role='button' />",
+    "<TestComponent @click='foo' />",
+    "<input @click='void 0' type='hidden' />",
+    "<span @click='submitForm'>Submit</span>",
+    "<span @click='submitForm' tabindex='undefined'>Submit</span>",
+    "<span @click='submitForm' tabindex='bad'>Submit</span>",
+    "<span @click='doSomething' tabindex='0'>Click me!</span>",
+    "<span @click='doSomething' :tabindex='0'>Click me!</span>",
+    "<span @click='doSomething' tabindex='-1'>Click me too!</span>",
+    "<a href='javascript:void(0);' @click='doSomething'>Click ALL the things!</a>",
+    "<section @click='void 0' />",
+    "<main @click='void 0' />",
+    "<article @click='void 0' />",
+    "<header @click='void 0' />",
+    "<footer @click='void 0' />",
+    ...rule.interactiveRoles.map((role) => ({
+      code: `<div role='${role}' tabindex='0' @click='void 0' />`,
+      options: [{ tabbable: rule.interactiveRoles }]
+    })),
+    "<div role='tab' tabindex='0' @click='void 0' />",
+    "<div role='textbox' tabindex='0' @click='void 0' />",
+    "<div role='textbox' aria-disabled='true' @click='void 0' />",
+    "<Foo.Bar @click='void 0' aria-hidden='false' />",
+    "<Input @click='void 0' type='hidden' />"
+  ],
+  invalid: [
+    ...rule.interactiveRoles.flatMap((role) =>
+      rule.interactiveHandlers.map((handler) => ({
+        code: `<div role='${role}' @${handler}='void 0' />`,
+        options: [{ tabbable: rule.interactiveRoles }],
+        errors: [{ message: rule.makeTabbableErrorMessage(role) }]
+      }))
+    ),
+    ...rule.interactiveRoles.flatMap((role) =>
+      rule.interactiveHandlers.map((handler) => ({
+        code: `<div role='${role}' @${handler}='void 0' />`,
+        options: [{ tabbable: [] }],
+        errors: [{ message: rule.makeFocusableErrorMessage(role) }]
+      }))
+    )
+  ]
+});

src/rules/interactive-supports-focus.js

@@ -0,0 +1,150 @@
+const { dom, roles } = require("aria-query");
+
+const {
+  defineTemplateBodyVisitor,
+  getAttributeValue,
+  getElementAttribute,
+  getElementAttributeValue,
+  getElementType,
+  hasOnDirectives,
+  isHiddenFromScreenReader,
+  isInteractiveElement,
+  isPresentationRole,
+  makeDocsURL
+} = require("../utils");
+
+const interactiveRoles = [];
+
+for (const [role, definition] of roles) {
+  if (
+    !definition.abstract &&
+    definition.superClass.some((classes) => classes.includes("widget"))
+  ) {
+    interactiveRoles.push(role);
+  }
+}
+
+const interactiveHandlers = [
+  "click",
+  "contextmenu",
+  "dblclick",
+  "doubleclick",
+  "drag",
+  "dragend",
+  "dragenter",
+  "dragexit",
+  "dragleave",
+  "dragover",
+  "dragstart",
+  "drop",
+  "keydown",
+  "keypress",
+  "keyup",
+  "mousedown",
+  "mouseenter",
+  "mouseleave",
+  "mousemove",
+  "mouseout",
+  "mouseover",
+  "mouseup"
+];
+
+const isDisabledElement = (node) =>
+  getElementAttributeValue(node, "disabled") ||
+  (getElementAttributeValue(node, "aria-disabled") || "").toString() === "true";
+
+const hasInteractiveRole = (node) => {
+  const roleValue = getElementAttributeValue(node, "role");
+  if (typeof roleValue !== "string") {
+    return false;
+  }
+
+  return roleValue
+    .toLowerCase()
+    .split(" ")
+    .some((role) => roles.has(role) && interactiveRoles.includes(role));
+};
+
+const hasTabIndex = (node) => {
+  const attribute = getElementAttribute(node, "tabindex");
+
+  if (!attribute) {
+    return false;
+  }
+
+  const value = getAttributeValue(attribute);
+
+  if (["string", "number"].includes(typeof value)) {
+    if (typeof value === "string" && value.length === 0) {
+      return false;
+    }
+    return Number.isInteger(Number(value));
+  }
+
+  if (value === true || value === false) {
+    return false;
+  }
+
+  return value === null;
+};
+
+const makeTabbableErrorMessage = (role) =>
+  `Elements with the "${role}" interactive role must be tabbable.`;
+
+const makeFocusableErrorMessage = (role) =>
+  `Elements with the "${role}" interactive role must be focusable.`;
+
+module.exports = {
+  meta: {
+    docs: {
+      url: makeDocsURL("interactive-supports-focus")
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          tabbable: {
+            type: "array",
+            items: {
+              type: "string",
+              enum: interactiveRoles
+            },
+            uniqueItems: true,
+            additionalItems: false
+          }
+        }
+      }
+    ]
+  },
+  create(context) {
+    return defineTemplateBodyVisitor(context, {
+      VElement(node) {
+        if (
+          dom.has(getElementType(node)) &&
+          hasOnDirectives(node, interactiveHandlers) &&
+          !hasTabIndex(node) &&
+          !isDisabledElement(node) &&
+          !isHiddenFromScreenReader(node) &&
+          !isPresentationRole(node) &&
+          hasInteractiveRole(node) &&
+          !isInteractiveElement(node)
+        ) {
+          const role = getElementAttributeValue(node, "role");
+          const { tabbable = [] } = context.options[0] || {};
+
+          if (role && tabbable.includes(role)) {
+            // Always tabbable, tabIndex = 0
+            context.report({ node, message: makeTabbableErrorMessage(role) });
+          } else {
+            // Focusable, tabIndex = -1 or 0
+            context.report({ node, message: makeFocusableErrorMessage(role) });
+          }
+        }
+      }
+    });
+  },
+  interactiveHandlers,
+  interactiveRoles,
+  makeTabbableErrorMessage,
+  makeFocusableErrorMessage
+};

src/utils.js

@@ -11,6 +11,7 @@ const hasOnDirectives = require("./utils/hasOnDirectives");
 const isAttribute = require("./utils/isAttribute");
 const isHiddenFromScreenReader = require("./utils/isHiddenFromScreenReader");
 const isInteractiveElement = require("./utils/isInteractiveElement");
+const isPresentationRole = require("./utils/isPresentationRole");
 const makeDocsURL = require("./utils/makeDocsURL");
 const matchesElementRole = require("./utils/matchesElementRole");
 
@@ -66,6 +67,7 @@ module.exports = {
   isAttributeWithValue,
   isHiddenFromScreenReader,
   isInteractiveElement,
+  isPresentationRole,
   makeDocsURL,
   matchesElementRole
 };

src/utils/isPresentationRole.js

@@ -0,0 +1,8 @@
+const getElementAttributeValue = require("./getElementAttributeValue");
+
+const isPresentationRole = (node) => {
+  const role = getElementAttributeValue(node, "role");
+  return role && ["presentation", "none"].includes(role);
+};
+
+module.exports = isPresentationRole;