[EuiPopover][EuiInputPopover] Allow more control via focusTrapProps

[cee-chen]

Summary

@Heenawter is working on a custom EuiSelectable component that has a filter dropdown/popover selection menu in between the search box and the listbox. This filter popover has special custom focus behavior that returns focus to the searchbox after filter select, and not to the toggling popover button.

The solution their usage needs is something like this:

<EuiPopover
  closePopover={}
  focusTrapProps={{
    returnFocus: false,
    onEscapeKey: // custom callback closing the popover and focusing the searchbox
    onDeactivation: // custom callback focusing the searchbox
  }}
/>

Unfortunately EuiPopover's default focus return behavior is getting in the way of their custom focus behavior. We should loosen the spread behavior of focusTrapProps to allow consumers to control focus UX as needed.

Breaking change

This PR also incidentally removes a prop (onTrapDeactivation) that is completely unused in EUI and Kibana (as well as untested and undocumented in EUI) that is duplicative of focusTrapProps behavior. I've opinionatedly left in other semi-duplicative focus trap props such as initialFocus and ownFocus because those have actual documentation in EUI as well as usages in Kibana.

QA

Mostly regression testing to ensure past behavior works as before; @Heenawter has QA'd that new behavior works in her app.

• Confirm EuiInputPopover continues to focus trap & dismiss its focus trap the same as on production
• Confirm the basic EuiPopover examples continue to focus trap & dismiss its focus trap as on prod
• Confirm the focus examples on EuiPopover's docs pages work the same as on prod

General checklist

• Checked for accessibility including keyboard-only and screenreader modes
• Props have proper autodocs (using @default if default values are missing) and playground toggles
  • [ ] Added documentation - No onTrapDeactivation docs, and IMO the concept of focusTrapProps is self-evident and already documented in its props
  • [ ] Added or updated jest and cypress tests - also skipped because no meaningful logic other than basic spread behavior was changed, which should also be self-evident
• Checked for breaking changes and labeled appropriately
• A changelog entry exists and is marked appropriately

- [ ] Checked in both light and dark modes
- [ ] Checked in mobile
- [ ] Checked in Chrome, Safari, Edge, and Firefox
- [ ] Checked Code Sandbox works for any docs examples
- [ ] Updated the Figma library counterpart

[cee-chen]

@Heenawter Do you mind testing this branch either in Kibana a la carte or by using our local Testing in Kibana steps to ensure this change does actually fix your issue? 🙏

[kibanamachine]

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

[Heenawter]

Tested this in a local Kibana instance and it indeed makes the fix discussed in #6627 (comment) possible without the need for any delay/timeout - thanks so much for working on this 🎉

[cee-chen]

jenkins test this

[cee-chen]

@1Copenut Do you mind giving this PR a quick review and smoke test? (see regression QA steps in PR description)

Should hopefully not take too long - hoping to get this in for tomorrow's release, although please feel free to shout if you'd rather hold or if you think it's at all risky.

[kibanamachine]

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

[1Copenut]

👍 LGTM! I tested the manual QA processes in Chrome for keyboard navigation behavior, and Safari, Firefox + VO for screen reader consistency with prod.