[EuiContextMenuPanel] Fix popover toggle focus restoration issues and remove need for watchedItemProps

[cee-chen]

Summary

I am once again asking you all to look at my memes:

Me fixing a single EuiContextMenu issue: Ah yes I know what the problem is, it's a quick 30 min fix
Me several hours and many E2E tests later: Haha yes, I've basically successfully rewritten the component

I strongly recommend reviewing by commit, although I will also try and lay out the rabbit hole I descended into below:

I thought you fixed this in #5760, what happened?

The fix in #5760 was implemented only for Escape key usage, because I basically forgot that consumers can manually close popovers from within the popover 🤦

So while the above PR is still generally useful for keyboard users and scenarios where focus gets stranded from popovers, this fix applies to EuiContextMenuPanel specifically and should hopefully be the final fix (knock on wood).

OK so why is this bug happening?

Essentially the issue is we need to let our focus trap library do its thing and stop messing up its returnFocus logic by setting focus too early (see this previous comment: #5760 (comment)).

So we detect when EuiContextMenuPanel is in a popover, and then I added a delay when it's in a popover to not run its updateFocus() call until EuiPopover has finished doing its thing. Boom, no more focus hijacking!

Wait but why the huge refactor then

OK so here's the deal. I thought I was basically done after 2 commits (1e3d257 and f6c99b8) and that was it was a pretty clean and straightforward fix, per the last paragraph.

I was testing it on docs site and everything was great and working. Then I wrote E2E tests for it. And by a sheer stroke of dumb luck I wrote my test component using the children prop, and not the items prop (6ef9342). And it kept failing and failing and failing. And I was like what the heck, I know this is working locally.

So then somehow (still not sure how, pretty sure a fever dream?) I realized that focus was still not returning to the popover toggle if EuiContextMenuPanel was using the children API instead of items. Why? Because of these lines right here:

eui/src/components/context_menu/context_menu_panel.tsx

Lines 400 to 403 in a5be54f

	// it's not possible (in any good way) to know if `children` has changed, assume they might have
	if (this.props.children != null) {
	return true;
	}

Basically, a context menu with items updates less often and thus hijacks focus less often. children however... doesn't... so what was happening was that our focus trap was returning focus to the popover toggle button, but EuiContextMenuPanel with children was still updating focus and hijacking/stealing it back to the panel as the popover closed, and of course once the panel is removed from the DOM along with the popover, focus gets stranded, yet again.

So what was the fix?

I basically table flipped and removed everything around our shouldComponentUpdate logic. EuiContextMenuPanel now updates like a regular component, removing the need for watchedItemsProps.

To make focus work as before, I then had to:

• Entirely change updateFocus() - I renamed it takeInitialFocus() made it only call once on panel init (1fb9b24).
• I moved the tabbable logic that populates state.menuItems out of updateFocus() and into its own thing (40dc5c4)
• I changed incrementFocusedItemIndex() to focusMenuItem() and made the method do its own .focus()ing instead of relying on updateFocus() to handle it. This restored arrow navigation to as before. (4b397b0)
• There's some small other little edge cases I hardened for that are noted in either commit messages or had E2E tests written.

All the commits around this set of changes are prefixed with [!!!]. Phew, I think that's it.

Checklist

- [ ] Checked in both light and dark modes
- [ ] Checked in mobile
- [ ] Props have proper autodocs and playground toggles
- [ ] Added documentation
- [ ] Checked Code Sandbox works for any docs examples
- [ ] Updated the Figma library counterpart

• Checked in Chrome, Safari, Edge, and Firefox
• Added or updated jest and cypress tests
• Checked for breaking changes and labeled appropriately
• Checked for accessibility including keyboard-only and screenreader modes
• A changelog entry exists and is marked appropriately

[kibanamachine]

Preview documentation changes for this PR: https://eui.elastic.co/pr_5880/

[kibanamachine]

Preview documentation changes for this PR: https://eui.elastic.co/pr_5880/

[thompsongl]

Going to add @1Copenut as a reviewer for some extra keyboard & SR coverage

[cee-chen]

FWIW I thought screen reader experience was kinda medium (e.g. I feel like the back button titles should have an extra hint that it goes back to the previous panel), but it shouldn't have changed / be any worse than it currently is on prod 🤔 Might be nice to add a follow-up ticket for this some day

[1Copenut]

LGTM! I took your advice @constancecchen and read through the code changes one commit at a time. The comments and rationale for refactoring were very helpful.

Putting the update through its paces with keyboard and VoiceOver navigation yielded a more refined experience, esp. with VO. The focus management now reads exactly what text element has focus. It does not start reading one thing, then stop and read another as focus shifts so rapidly not to be seen, but to be heard.

Many thanks for adding all of the Cypress test cases and a regression short circuit. I think this will yield even bigger improvements for NVDA and JAWS where they use a different accessibility logic paradigm than VO.

[cee-chen]

Thanks a million @1Copenut! ❤️

@thompsongl, did you want to review this PR, or should I go ahead and merge with just Trevor's approval?

[thompsongl]

I'll review this afternoon. Thanks for the quick turnaround, @1Copenut!

[thompsongl]

Looking good! I like the approach to "let the focus trap do all the work"

[thompsongl]

++

[thompsongl]

Could you throw a comment in the files where these class names are created/added about being used as selectors here? To prevent accidental deletion during Emotion conversions and/or up force us to update these to something else if we want to remove the class names.

[cee-chen]

TBH, I'd love a less DOM-dependent way of figuring out whether an EuiContextMenu/Panel is inside an EuiPopover. Just spitballing, but what if we do something like React.cloneElement on popover children and checking for type === EuiContextMenu || EuiContextMenuPanel, and setting an isInPopover flag if so? We can avoid all these issues with classNames in that case.

[thompsongl]

Worth trying! Looks like we already do that kind of thing in this file:

eui/src/components/context_menu/context_menu_panel.tsx

Lines 503 to 505 in fcd9fae

	return MenuItem.type === EuiContextMenuItem
	? cloneElement(MenuItem, cloneProps)
	: MenuItem;

[cee-chen]

I spiked this out for a bit in EuiPopover but it ended up being a bit of a ref nightmare so I gave up (due to either render order or the way popover stores refs, the panel ref is null / isn't available on EuiContextMenuPanel mount). I converted the .euiPopover__panel check to hook onto a data attribute instead instead. I left euiContextMenu alone since we haven't been removing top-level CSS classes as part of our Emotion conversion.

f8e7a5c

TBH if we ever do completely remove CSS classNames from EUI we're going to have to do a lot of grepping so I don't super see the need to add a comment, especially since EuiContextMenu is directly in the same component + E2E tests will immediately fail for this if the class name is removed.

[kibanamachine]

Preview documentation changes for this PR: https://eui.elastic.co/pr_5880/

[cee-chen]

jenkins test this

[kibanamachine]

Preview documentation changes for this PR: https://eui.elastic.co/pr_5880/