Improve VoiceOver experience when reordering menus #18155

twstokes · 2022-03-17T01:38:08Z

Description

This PR aims to improve the VoiceOver experience when reordering menu items:

When a menu item drag handle is selected, VoiceOver should no longer say "dimmed" which implies that the button isn't enabled.
When a menu item drag handle is selected, VoiceOver should now mention that lateral movements can change the item's hierarchy.
When a menu item label is selected (the main button), the button's parent is now included to give a sense of hierarchy.
When a menu item is moved, VoiceOver now announces if the item has a new parent and / or is above or below a sibling.

Before (contains audio) 🔈	After (contains audio) 🔈
Before.MP4	After.MP4

Testing

ℹ️ Note: It can be helpful to enable triple-clicking to toggle VoiceOver.

Prerequisites:

A WordPress theme with menu support (any of the basic free themes should work)
A WordPress user with the permissions to edit menus

Preconditions for each test:

Access the Menus view from the "My Site" view
Match the "Before" menu structure if a test defines it (it can be helpful to toggle VoiceOver temporarily off while structuring the menu)
VoiceOver is enabled when the test is started

Test 1 - Move Item C to be a child of Item A, under Item B

Before:

Item A
- Item B
  - Item C

After:

Item A
- Item B
- Item C

Expected VO (VoiceOver): "Child of [Item A], after [Child B]"

Test 2 - Move Item A to be a child of Item B

Before:

Item A
Item B

After:

Item B
- Item A

Expected VO: "Child of [Item B]"

Note: If an Item C exists after Item B that Item A is inserted above, we still only expect "Child of [Item B]" and not "Child of [Item B] above [Item C]."

Test 3 - Move Item B to become a sibling of its parent at the top level

Before:

Item A
- Item B

After:

Item A
Item B

Expected VO: "Top level. After [Item A]"

Test 4 - Move Item C to become a sibling of its parent

Before:

Item A
- Item B
  - Item C

After:

Item A
- Item B
- Item C

Expected VO: "Child of [Item A]. After [Item B]"

Test 5 - Move Item A after Item B

Before:

Item A
Item B

After:

Item B
Item A

Expected VO: "After [Item B]"

Test 6 - Move Item B above Item A

Before:

Item A
Item B

After:

Item B
Item A

Expected VO: "Before [Item A]"

⚠️ Known Limitations:

If Item A is moved quickly to be a child of Item B below existing children, VO will not announce the new parent. This is due to multiple VO events firing in quick succession and it's using the latest VO string (which is equivalent to Test 5).

Example:

Before:

Item A
Item B
- Item C
- Item D
- Item E
- Item F

After:

Item B
- Item C
- Item D
- Item A
- Item E
- Item F

Expected VO: "After [Item D]"

The same applies in the opposite direction:

If Item A is moved quickly to be a child of Item B above existing children, VO will not announce the new parent. This is because multiple VO events fired due to the quick succession and it's using the latest VO string which is equivalent to Test 6.

Test 7 - Hover over the main button

If a child of a menu item:

Expected VO: "[Name of item] child of [parent menu item]. Button. Edits this menu item."

If the top level (no parent):

Expected VO: "[Name of item] top level. Button. Edits this menu item."

Test 8 - Hover over the drag handle

Move the VoiceOver focus to the drag handle on the right of a menu item.

Expected VO: "Move [name of item]. Button. Double-tap to move this menu item up or down. Move horizontally to change hierarchy."

VO no longer announces "Dimmed" as the button state. More context.

Test 9 - Saving reordered menu items

Reorder menu items using VoiceOver and save the menu structure.
Confirm that the new menu structure is reflected in the app and on the web.

Test cases:

- [ ] Test 1 - Move Item C to be a child of Item A, under Item B
- [ ] Test 2 - Move Item A to be a child of Item B
- [ ] Test 3 - Move Item B to become a sibling of its parent at the top level
- [ ] Test 4 - Move Item C to become a sibling of its parent
- [ ] Test 5 - Move Item A after Item B
- [ ] Test 6 - Move Item B above Item A
- [ ] Test 7 - Hover over the main button
- [ ] Test 8 - Hover over the drag handle
- [ ] Test 9 - Saving reordered menu items

Regression Notes

Potential unintended areas of impact

Menu ordering
Menu saving
VoiceOver output on the Menus view
- Creating menu items
- Deleting menu items
- Moving menu items
- Hovering over menu items
Localization of VoiceOver strings

Functionality to the Menus view should be unchanged when VoiceOver is off.

What I did to test those areas of impact (or what existing automated tests I relied on)
I manually tested all tests above.
What automated tests I added (or what prevented me from doing so)

PR submission checklist:

I have completed the Regression Notes.
I have considered adding unit tests for my changes.
I have considered adding accessibility improvements for my changes.
I have considered if this change warrants user-facing release notes and have added them to RELEASE-NOTES.txt if necessary.

wpmobilebot · 2022-03-17T02:00:36Z

You can test the Jetpack changes on this Pull Request by downloading it from AppCenter here with build number: pr18155-5c4e4be. IPA is available here. If you need access to this, you can ask a maintainer to add you.

wpmobilebot · 2022-03-17T02:02:22Z

You can test the WordPress changes on this Pull Request by downloading it from AppCenter here with build number: pr18155-5c4e4be. IPA is available here. If you need access to this, you can ask a maintainer to add you.

wpmobilebot · 2022-03-29T20:21:09Z

You can test the changes in Jetpack from this Pull Request by:

Clicking here or scanning the QR code below
Then installing the build number pr18155-c41c600 from App Center on your iPhone

The .ipa file can also be downloaded directly here.
If you need access to App Center, please ask a maintainer to add you.

wpmobilebot · 2022-03-29T20:23:51Z

You can test the changes in WordPress from this Pull Request by:

Clicking here or scanning the QR code below
Then installing the build number pr18155-c41c600 from App Center on your iPhone

The .ipa file can also be downloaded directly here.
If you need access to App Center, please ask a maintainer to add you.

mokagio · 2022-04-03T21:22:09Z

I'm going to bump this to the next release because we'll be code freezing 19.6 next week and this is still a draft.

It doesn't seem the case, but if it's very important that this makes it into this release, let me know and we'll organize a new beta once ready.

twstokes · 2022-04-03T21:31:12Z

Thanks @mokagio, 19.7 works just fine.

guarani · 2022-04-08T19:54:22Z

Test 4 - Move Item B to become a sibling of its parent

I think this should say "Item C", but I'm loving how neatly set out the test cases are.

twstokes · 2022-04-08T20:01:27Z

Test 4 - Move Item B to become a sibling of its parent

I think this should say "Item C", but I'm loving how neatly set out the test cases are.

Thanks @guarani! This is now fixed.

guarani

Tested using build pr18155-c41c600 and everything works as expected, nice work @twstokes!

Test 1 - Move Item C to be a child of Item A, under Item B
Test 2 - Move Item A to be a child of Item B
Test 3 - Move Item B to become a sibling of its parent at the top level
Test 4 - Move Item C to become a sibling of its parent
Test 5 - Move Item A after Item B
Test 6 - Move Item B above Item A
Test 7 - Hover over the main button
Test 8 - Hover over the drag handle
Test 9 - Saving reordered menu items

guarani · 2022-04-08T21:14:19Z

WordPress/WordPressTest/Menus/MenuItemTests.swift

+        let entityName = MenuItem.classNameWithoutNamespaces()
+        let entity = NSEntityDescription.insertNewObject(forEntityName: entityName, into: context)
+
+        let menuItem = entity as! MenuItem


[nitpick comment] XCTUnwrap(entity as? MenuItem) could be used here, but I'm not sure if it fits this context since this is a helper method and if the force-cast failed, it would be due to a programming error rather than a test failure.

That's a good thought @guarani! Since the type shouldn't change and this is in the context of a test, I'm considering letting it stay as is. I believe this could only fail if some really bad stuff happened under the hood with Core Data.

Sounds good!

twstokes self-assigned this Mar 17, 2022

twstokes added 2 commits March 20, 2022 19:27

Override the accessibility traits so that VoiceOver doesn't say 'Dimmed'

3271d04

Add a note to a11y hint about changing hierarchy.

16efa17

twstokes force-pushed the feature/menu-vo-order branch from d4fc778 to faed559 Compare March 20, 2022 23:27

twstokes added 3 commits March 21, 2022 15:33

Add MenuItem method for finding preceding siblings.

c5c4d6e

Add method to refresh a11y labels.

12303f2

Announce changes to menu ordering when VO is enabled.

5c4e4be

twstokes force-pushed the feature/menu-vo-order branch from faed559 to 5c4e4be Compare March 21, 2022 20:49

twstokes changed the title ~~Improve VoiceOver experience in Menus view~~ Improve VoiceOver experience when reordering menus Mar 21, 2022

twstokes added the Menus label Mar 21, 2022

twstokes added this to the 19.6 milestone Mar 21, 2022

Merge remote-tracking branch 'origin/trunk' into feature/menu-vo-order

0beed5b

twstokes added 5 commits March 30, 2022 14:00

Merge remote-tracking branch 'origin/trunk' into feature/menu-vo-order

a90db1b

Add tests for VoiceOver strings.

fdfdf9a

Touch up comments.

4db1267

Add tests for menu items.

d3f0a72

Add descendant tests.

23f609a

twstokes force-pushed the feature/menu-vo-order branch 2 times, most recently from 8a6463f to f7275d5 Compare March 31, 2022 21:57

Cleanup tests.

7cbfaf0

twstokes force-pushed the feature/menu-vo-order branch from f7275d5 to 7cbfaf0 Compare March 31, 2022 21:57

mokagio modified the milestones: 19.6, 19.7 Apr 3, 2022

twstokes marked this pull request as ready for review April 5, 2022 15:36

twstokes added 2 commits April 5, 2022 12:12

Merge remote-tracking branch 'origin/trunk' into feature/menu-vo-order

e2f406c

Add release note.

c41c600

twstokes added [Type] Enhancement Accessibility labels Apr 6, 2022

guarani self-requested a review April 8, 2022 19:54

guarani approved these changes Apr 8, 2022

View reviewed changes

twstokes merged commit 9dddadb into trunk Apr 8, 2022

twstokes deleted the feature/menu-vo-order branch April 8, 2022 21:29

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve VoiceOver experience when reordering menus #18155

Improve VoiceOver experience when reordering menus #18155

twstokes commented Mar 17, 2022 •

edited

Loading

wpmobilebot commented Mar 17, 2022 •

edited

Loading

wpmobilebot commented Mar 17, 2022 •

edited

Loading

wpmobilebot commented Mar 29, 2022 •

edited

Loading

wpmobilebot commented Mar 29, 2022 •

edited

Loading

mokagio commented Apr 3, 2022

twstokes commented Apr 3, 2022

guarani commented Apr 8, 2022

twstokes commented Apr 8, 2022 •

edited

Loading

guarani left a comment

guarani Apr 8, 2022 •

edited

Loading

twstokes Apr 8, 2022

guarani Apr 11, 2022

Improve VoiceOver experience when reordering menus #18155

Improve VoiceOver experience when reordering menus #18155

Conversation

twstokes commented Mar 17, 2022 • edited Loading

Description

Testing

Before:

After:

Before:

After:

Before:

After:

Before:

After:

Before:

After:

Before:

After:

Before:

After:

Regression Notes

wpmobilebot commented Mar 17, 2022 • edited Loading

wpmobilebot commented Mar 17, 2022 • edited Loading

wpmobilebot commented Mar 29, 2022 • edited Loading

wpmobilebot commented Mar 29, 2022 • edited Loading

mokagio commented Apr 3, 2022

twstokes commented Apr 3, 2022

guarani commented Apr 8, 2022

twstokes commented Apr 8, 2022 • edited Loading

guarani left a comment

Choose a reason for hiding this comment

guarani Apr 8, 2022 • edited Loading

Choose a reason for hiding this comment

twstokes Apr 8, 2022

Choose a reason for hiding this comment

guarani Apr 11, 2022

Choose a reason for hiding this comment

twstokes commented Mar 17, 2022 •

edited

Loading

wpmobilebot commented Mar 17, 2022 •

edited

Loading

wpmobilebot commented Mar 17, 2022 •

edited

Loading

wpmobilebot commented Mar 29, 2022 •

edited

Loading

wpmobilebot commented Mar 29, 2022 •

edited

Loading

twstokes commented Apr 8, 2022 •

edited

Loading

guarani Apr 8, 2022 •

edited

Loading