Modal: Expose Modal heading reference

[silvalaura]

There have been various use cases presented where it would be beneficial for adopters to be able to manually refocus the heading inside the modal. We own the heading and the heading ref completely, so it's currently not impossible with a clean solution. This has come up a few times for multiple teams from Perkins reviews.

Current Workaround:

  useEffect(() => {
    setTimeout(() => {
      const headings = document.querySelectorAll('h1');
      const targetHeading = Array.from(headings).filter(
        heading => heading.innerText === transformDialogTitle(activeDialog)
      )[0];
      setHeadingNode(targetHeading);
    }, 100);
  }, [activeDialog]);

Acceptance Criteria

• The Modal component accepts a headingRef prop so we can give adopters better control.
• There is an example of this new prop working in both storybook and docs site, where a Modal has a custom heading and it can be programmatically focused
• The Drawer component is built on the Modal, so this should also be documented and function for Drawer

[chris-cedrone-cengage]

Should we explore alternatives to using a specific ref as a prop? Perhaps there's another way to pass the focus on a custom header component.

The biggest concern is how we presently use a tabindex="-1" in our Heading component within the Modal itself and somehow replicating that to a prop(s) somehow.

[silvalaura]

We can use something like this example for the docs site example of a modal with a custom heading

[silvalaura]

Testing Notes:

1. The Modal Header example on codesandbox has an error with multiple missing imports:

2. It may be helpful to also mention the necessary tabIndex prop in the docs: ```When a reference to the header is needed, use the headerRef prop. When using a custom header, you must also use tabIndex={-1} property.`

3. The example for This modal has a header has text that says This modal has no header.

[silvalaura]

@chris-cedrone-cengage Sorry I missed it too, CheckIcon needs to be imported from react-magma-icons, not dom 😢. The rest looks great

[silvalaura]

Looks good!