feat: improve logic for modal/flyout lifecycle handling

[shleewhite]

📌 Summary

If merged, this PR would use registerDestructor to trigger the close callback when a Modal or Flyout is closed to ensure the proper cleanup happens when a Modal/Flyout is removed from the DOM.

TODO:

• test in cloud ui (it was tested in cloud ui back in june, but will test again)

🛠️ Detailed description

There are 2 commits in this branch, one to simplify the lifecycle logic and another to fix the click outside to dismiss bug.

Lifecycle logic

This is a follow up from the Modal incident that happened earlier this summer when the modal is simply destroyed and removed from the DOM (eg. on submit) the onDismiss is not run, just the willDestroyNode method, which leaves the overflow applied to the body, making the page unscrollable.

A version of this solution was previously suggested in #2962, but was not used because it was safer to just revert the change that caused the bug.

The fix now is to refactor the did-insert and will-destroy functions into a new modifier registerDialog. This way, it is guaranteed to run when the component is inserted in the DOM and the cleanup function will run when it is removed.

Click outside to dismiss (TBD)

There is also a fix for the pre-existing bug in the Modal where if @isDismissDisabled is set to true, you cannot click outside to dismiss the Modal is allowed to be dismissed again (existing showcase with the bug).

To fix this, I recreate the click outside to dismiss functionality from ember-focus-trap in the Modal component.

In the showcase, this causes extra click event handlers to be added to the DOM because of the perpetually "open" inline modal examples for VRT. The click event handlers are added and removed correctly for the demos at the bottom of the page.

NOTE: If we decide the click outside to dismiss change is too much to include in this PR, I can totally remove the commit.

Preview showcase

🔗 External links

Jira ticket: HDS-5038

---

👀 Component checklist

• Percy was checked for any visual regression
• A changelog entry was added via Changesets if needed (see templates here)

💬 Please consider using conventional comments when reviewing this PR.

📋 PCI review checklist

• If applicable, I've documented a plan to revert these changes if they require more than reverting the pull request.
• If applicable, I've worked with GRC to document the impact of any changes to security controls.
  Examples of changes to controls include access controls, encryption, logging, etc.
• If applicable, I've worked with GRC to ensure compliance due to a significant change to the in-scope PCI environment.
  Examples include changes to operating systems, ports, protocols, services, cryptography-related components, PII processing code, etc.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Updated (UTC)
hds-showcase	Ready	Preview	Oct 1, 2025 1:24pm
hds-website	Ready	Preview	Oct 1, 2025 1:24pm

[github-actions]

📦 RC Packages Published

Latest commit: aedaa64

Published 2 packages

@hashicorp/[email protected]

yarn up -C @hashicorp/design-system-components@rc

@hashicorp/[email protected]

yarn up -C @hashicorp/design-system-tokens@rc

[didoo]

A few high-level comments:

---

All these explanations need to be updated to reflect the new code logic (willDestroyNode doesn't exist anymore)

The same on the Modal showcase demos.

---

I suspect there is still something not 100% working at logical level, see video below where the listener for the close event seems not to be removed (that's my understanding, but I may be wrong).

Screen.Recording.2025-09-25.at.12.08.45.mov

I suggest to review all the use cases using a reduced set of examples, and making sure (via debugger that the order of execution is what you would expect, for different ways to close the flyout). I've sent you a code patch in DM if you want to use it.

[shleewhite]

@didoo I looked into it more and I believe the fix you suggested was enough to make sure all the event listeners are removed correctly.

[dchyun]

Minus the one open question on the differences between the modal and the flyout this looks all good to me!

[dchyun]

Fixes all look good to me!

[didoo]

LGTM 👌