[EuiModal] Support focusTrapProps to handle manual return focus

[mgadewoll]

Summary

This PR updates EuiModal and adds the prop focusTrapProps. This update aims to support manually returning focus on closing a modal in the same way that EuiFlyout does.
Currently when the focus is not being returned automatically, the only way to return focus on closing a modal is to do it as part of the onClose callback.

Additional changes

• adds documentation about manually returning focus on closing EuiModal and EuiFlyout

EuiModal	EuiFlyout

Why are we making this change?

Aligning the API for the same functionality across different components.

Screenshots

Screen.Recording.2025-08-05.at.17.57.28.mov

Impact to users

🟢 There are no updates needed on consumer side.

QA

• added cypress tests pass
• using this story, verify the focus is returned to the custom trigger, instead of the original trigger element

General checklist

• Browser QA
  • Checked in both light and dark modes
  • Checked in both MacOS and Windows high contrast modes
    • (emulate forced colors if you do not have access to a Windows machine.)
  • Checked in mobile
  • Checked in Chrome, Safari, Edge, and Firefox
  • Checked for accessibility including keyboard-only and screenreader modes
• Docs site QA
  • Added documentation
  • Props have proper autodocs (using @default if default values are missing) and playground toggles
  • Checked Code Sandbox works for any docs examples
• Code quality checklist
  • Added or updated jest and cypress tests
  • Updated visual regression tests
• Release checklist
  • A changelog entry exists and is marked appropriately.
  • If applicable, added the breaking change issue label (and filled out the breaking change checklist)
• Designer checklist
  • If applicable, file an issue to update EUI's Figma library with any corresponding UI changes. (This is an internal repo, if you are external to Elastic, ask a maintainer to submit this request)

[elasticmachine]

💚 Build Succeeded

• Buildkite Build
• Commit: 52c5409
• Documentation website
• Storybook

cc @mgadewoll

[elasticmachine]

💚 Build Succeeded

• Buildkite Build
• Commit: 52c5409

cc @mgadewoll

[weronikaolejniczak]

LGTM! 🟢 Tested the story, verified doc entries are correct, and checked the implementation.

Not that important but the EuiModal / EuiFlyout docs screenshots were hosted on https://private-user-images.githubusercontent.com/ so when I click on them, I don't have access. It's fine though, I used the staging link. Might be worth to take a look into though for future PRs.