[a11y] Resource list has labeling and focus issues

[dpersing]

Issue summary

The Resource List implementation may present some challenges to screen reader and keyboard-only users.

Bulk actions

"Hidden" controls are available

• On desktop, checking the bulk checkbox (Showing 2 customers) or the bulk button at smaller breakpoints (Select) with the keyboard (space) causes focus to disappear from the page. (It's actually gone to the off-screen checkbox/button that's been replaced by the new visible bulk actions, which are layered using z-index.) Pressing tab causes it to reappear on the visible checked checkbox, but users may be confused about where focus has gone.
• The off-screen bulk checkbox or button is readable and focusable by screen readers, which may cause confusion for non-visual screen reader users.
• If the bulk checkbox is unchecked with the keyboard and no options are checked, focus moves off-screen. Pressing tab moves focus to the first resource list item link.

<div class="Polaris-ResourceList__SelectButtonWrapper">
  <button type="button" class="Polaris-Button Polaris-Button--disabled" disabled="">
    <span class="Polaris-Button__Content">
      <!-- ... -->
      <span>Select</span>
    </span>
  </button>
</div>

<!-- ... -->

<div class="Polaris-ResourceList__BulkActionsWrapper"><!-- ... --></div>

.Polaris-ResourceList__SelectButtonWrapper {
    position: relative;
    -ms-flex: none;
    flex: none;
}

.Polaris-ResourceList__BulkActionsWrapper {
    position: relative;
    z-index: 2;
    width: 100%;
}

Labels are unclear

• If there is a mixed state, the visible mixed state checkbox label is not reflected as part of the label that is read on focus. This may cause confusion for sighted keyboard users, especially in the context of the additional off-screen checkbox, as well as challenges for speech activation users.

<label class="Polaris-Choice Polaris-Choice--labelHidden" for="Checkbox131">
  <!-- ... -->
  <input id="Checkbox131" type="checkbox" class="Polaris-Checkbox__Input Polaris-Checkbox__Input--indeterminate" aria-invalid="false" role="checkbox" aria-checked="mixed" value="" indeterminate="true">
  <!-- ... -->
  <span class="Polaris-Choice__Label">Select all 2 customers</span>
</label>
<!-- ... -->
<span class="Polaris-ResourceList-CheckableButton__Label">1 selected</span>

• The individual resource item checkboxes do not have labels that convey which item they go with. Their labels also change based on their state, which may cause confusion since there's no clear context for which resource is related (Select item, unchecked, checkbox, Deselect item, checked, checkbox). This is being addressed by Add translations: default #1549.

<label class="Polaris-Choice Polaris-Choice--labelHidden" for="ResourceListItemCheckbox43">
  <!-- ... -->
  <input id="ResourceListItemCheckbox43" type="checkbox" class="Polaris-Checkbox__Input" aria-invalid="false" role="checkbox" aria-checked="false" value="">
  <!-- ... -->
  <span class="Polaris-Choice__Label">Select item</span>
</label>
<!-- ... -->
<label class="Polaris-Choice Polaris-Choice--labelHidden" for="ResourceListItemCheckbox44">
  <!-- ... -->
  <input id="ResourceListItemCheckbox44" type="checkbox" class="Polaris-Checkbox__Input" aria-invalid="false" role="checkbox" aria-checked="true" value="">
  <!-- ... -->
  <span class="Polaris-Choice__Label">Deselect item</span>
</label>

• On mobile, the individual list item checkboxes cannot be activated with VoiceOver running. They are identified as expected, but activating them does not change their state. There seems to be some sensitivity around how the actual checkbox <input> elements and their labels are visually hidden with clip, resulting in there not being a target. Checkboxes that have a visible label (or text that is nearby like the bulk checkbox :grimace:) seem to be working fine.

<label class="Polaris-Choice Polaris-Choice--labelHidden" for="ResourceListItemCheckbox43">
  <!-- ... -->
  <input id="ResourceListItemCheckbox43" type="checkbox" class="Polaris-Checkbox__Input" aria-invalid="false" role="checkbox" aria-checked="false" value="">
  <!-- ... -->
  <span class="Polaris-Choice__Label">Select item</span>
</label>

.Polaris-Checkbox__Input {
    position: absolute!important;
    top: 0;
    clip: rect(1px,1px,1px,1px)!important;
    overflow: hidden!important;
    height: 1px!important;
    width: 1px!important;
    padding: 0!important;
    border: 0!important;
}

.Polaris-Choice--labelHidden>.Polaris-Choice__Label {
    position: absolute!important;
    top: 0;
    clip: rect(1px,1px,1px,1px)!important;
    overflow: hidden!important;
    height: 1px!important;
    width: 1px!important;
    padding: 0!important;
    border: 0!important;
}

Shortcut actions

• Smaller-breakpoint, persistent shortcut action buttons have no text equivalent for the ... icon. Screen reader users may not be able to tell what the button does.

<button type="button" class="Polaris-Button Polaris-Button--plain Polaris-Button--iconOnly" tabindex="0" aria-controls="Popover29" aria-owns="Popover29" aria-haspopup="true" aria-expanded="false">
  <span class="Polaris-Button__Content">
    <span class="Polaris-Button__Icon">
      <span class="Polaris-Icon">
        <svg class="Polaris-Icon__Svg" viewBox="0 0 20 20" focusable="false" aria-hidden="true">
          <path d="M6 10a2 2 0 1 1-4.001-.001A2 2 0 0 1 6 10zm6 0a2 2 0 1 1-4.001-.001A2 2 0 0 1 12 10zm6 0a2 2 0 1 1-4.001-.001A2 2 0 0 1 18 10z" fill-rule="evenodd"></path>
        </svg>
      </span>
    </span>
  </span>
</button>

• Controls that repeat for persistent shortcut actions for each list item do not have unique text. Non-visual users may have difficulty distinguishing which resource item they relate to as they tab through the controls and hear them read.

<a class="Polaris-Button Polaris-Button--plain Polaris-Button--sizeSlim" href="orders/1456" data-polaris-unstyled="true">
  <span class="Polaris-Button__Content">
    <span>View latest order</span>
  </span>
</a>
<!-- ... -->
<a class="Polaris-Button Polaris-Button--plain Polaris-Button--sizeSlim" href="orders/1457" data-polaris-unstyled="true">
  <span class="Polaris-Button__Content">
    <span>View latest order</span>
  </span>
</a>

Steps to reproduce

I'm happy to run through these over video chat or record video if it would be helpful. (That's always the case, but this one is complex so it might be extra helpful.) There's currently a bug in WebKit that causes the browser to jump to the top when a user is trying to access iframe content with VoiceOver, so doing video on mobile is a pain and would probably require a demo.

Bulk actions

1. Navigate to Resource List and choose the bulk actions example from the dropdown.
2. Tab to the Showing 2 customers checkbox or the Select button and press Space to check/activate them and observe where focus goes.
3. Press tab to move focus through each control and activate it.
4. Repeat the process with a screen reader to hear how the off-screen and on-screen controls are identified and verify that all interactions are still available.
5. Repeat the process using VoiceOver on mobile.

Shortcut actions

1. Navigate to Resource List and choose either shortcut actions example from the dropdown.
2. Using a screen reader, tab or swipe to the resource links and the shortcut action controls to hear how they are read, at large and small breakpoints.

Behavior (tl;dr)

Expected

• Focus will not get lost when content dynamically updates.
• Focus will not move to off-screen/unavailable content.
• Control labels and link text will be clear.
• Control labels and link text provided programmatically will reflect visible labels and text.
• Interactive controls will be able to be used with the keyboard/gestures while assistive technology is running.

Actual

• Focus is lost when bulk checkboxes and buttons are activated, focus moves off-screen.
• Screen reader and keyboard focus can move to off-screen bulk controls that should not be available.
• The visible mixed state bulk label does not match the label that is read on focus.
• Resource checkboxes and shortcut actions don't have labels or text that are unique to the resource being accessed. This is being addressed for checkboxes in Add translations: default #1549.
• Resource checkboxes with no visible label/target size can't be toggled using VoiceOver on iOS.

Recommendations

• When the bulk controls are toggled, use display: none instead of relying on z-index alone to hide the controls that are off-screen and manage focus to the controls that are displayed.
• Use the visible mixed-state label for the bulk checkbox as part of the programmatic label so users can tell what the checkbox will do and also how it related to the summary of how many items are selected.

<label class="Polaris-Choice Polaris-Choice--labelHidden" for="Checkbox131">
  <!-- ... -->
  <input id="Checkbox131" type="checkbox" class="Polaris-Checkbox__Input Polaris-Checkbox__Input--indeterminate" aria-invalid="false" role="checkbox" aria-checked="mixed" value="" indeterminate="true">
  <!-- ... -->
  <span class="Polaris-Choice__Label">Select all 2 customers, </span>
  <span class="Polaris-ResourceList-CheckableButton__Label">1 selected</span>
</label>

• Give individual resource checkboxes for bulk actions a label that conveys which resource is related (Add translations: default #1549). Refrain from changing the label text based on the checkbox state, since screen readers convey the state automatically.
• To give VoiceOver/mobile Safari something to glom onto as a target, try using opacity: 0 instead of clip to hide the checkbox. This worked recently with a Safari bug (Bump handlebars from 4.1.0 to 4.1.2 in /examples/create-react-app #1626) and seems to allow a clipped label and custom radio button to be able to be targeted more easily. Alternately, I'd like to explore the option of letting the native checkbox stay visible as part of the discussion around making the checkbox have higher contrast (#129).

<label class="Polaris-Choice Polaris-Choice--labelHidden" for="ResourceListItemCheckbox43">
  <!-- ... -->
  <input id="ResourceListItemCheckbox43" type="checkbox" class="Polaris-Checkbox__Input" aria-invalid="false" role="checkbox" aria-checked="false" value="">
  <!-- ... -->
  <span class="Polaris-Choice__Label">Mae Jemison</span>
</label>
<!-- ... -->
<label class="Polaris-Choice Polaris-Choice--labelHidden" for="ResourceListItemCheckbox44">
  <!-- ... -->
  <input id="ResourceListItemCheckbox44" type="checkbox" class="Polaris-Checkbox__Input" aria-invalid="false" role="checkbox" aria-checked="true" value="">
  <!-- ... -->
  <span class="Polaris-Choice__Label">Ellen Ochoa</span>
</label>

• Give the shortcut action menu button a label that conveys its purpose and indicates which resource is related (ex.: <button aria-label="Actions for Mae Jemison" aria-controls="Popover29" aria-owns="Popover29" aria-haspopup="true" aria-expanded="false">)
• Give persistent shortcut actions labels/link text that convey which resource is related. Using the resource item <h3> and describedby would be sufficient.

Since this is a complex feature, I'd love to explore options for doing some usability testing with it as well.

Specifications

• Component: Resource List
• WCAG SCs: 2.1.1 Keyboard (Level A), 2.4.4 Link Purpose (In Context) (Level A), 2.4.7 Focus Visible (Level AA), 2.5.3 Label in Name (Level A), 3.3.2 Labels or Instructions (Level A)
• Testing done with:
  • Keyboard
  • VoiceOver/Safari/macOS
  • VoiceOver/Safari/iOS
  • NVDA/Firefox/Windows 10
  • Text resize
  • Windows High Contrast theme

[dpersing]

Removed Popover-specific issues to create a separate issue.

[dpersing]

Heyo @dleroux and @AndrewMusgrave! I know you've been doing some updates to the resource list so I wanted to see if you were able to knock out any of the issues listed here. I can schedule retesting this component if you think the changes you've made have had any impacts on keyboard support or labeling. Thanks!

[alex-page]

Fixing this issue should also remove a bunch of errors in this file:
https://github.com/Shopify/polaris-react/blob/master/a11y_shitlist.json

[dpersing]

@dleroux @AndrewMusgrave If I recall correctly, you're going to work on this as part of the resource list optimization work. Is it safe to move it to "on hold" and assign it to you @AndrewMusgrave?

[dleroux]

I discussed this one with Andrew and I'm still going to tackle it.

[dpersing]

Awesome, thanks @dleroux!