feat: Focus Management within ShadowDOM

[MahmoudElsayad]

Closes #1472

This PR enhances focus management capabilities in React Spectrum applications when used within Shadow DOM environments.

Changes

• Introduced a new utility function getRootNode, designed to return a given element's contextually appropriate root (Document or ShadowRoot). This improves the library's ability to query and manipulate focus within shadow DOMs.
• Added Shadow DOM support to the following:
  • FocusScope
  • useFocus
  • useFocusVisible
  • useFocusWithin
  • useInteractionOutside
  • usePress
• Implemented a new utility function, getRootBody that determines the effective "body" element for an event's propagation path, supporting both Shadow DOM and traditional document structures.
• implemented a new utility, ' getDeepActiveElement,` which retrieves the currently focused element across Shadow DOM boundaries, ensuring accurate focus management in complex DOM structures.
• Added tests for all new utility functions and affected hooks/components.

✅ Pull Request Checklist:

• Included link to corresponding React Spectrum GitHub Issue.
• Added/updated unit tests and storybook for this change (for new code or code which already has tests).
• Filled out test instructions.
• Updated documentation (if it already exists for this component).
• Looked at the Accessibility Practices for this feature - Aria Practices

📝 Test Instructions:

• Open any storybook example that uses any of the affected hooks/components
• Test the functionality and make sure it works when the story is encapsulated inside a shadow root.

// custom wrapper to run any story inside a shadow root
function ShadowDomWrapper({ children }) {
  const container = useRef(null);

  useEffect(() => {
    const _container = container.current;
    if (!_container) return;

    const div = document.createElement('div');
    _container.appendChild(div);

    const shadowRoot = div.attachShadow({ mode: 'open' });
    const main = document.createElement('main');
    shadowRoot.appendChild(main);

    // Wrap children with the ThemeProvider when rendering
    ReactDOM.render(
      children,
      main
    );

    return () => {
      ReactDOM.unmountComponentAtNode(main);
      if (_container) {
        _container.innerHTML = '';
      }
    };
  }, [children]);

  return <div ref={container} />;
}

// .storybook/preview.js
export const decorators = [
+    (Story) => (
+     <ShadowDomWrapper>
+        <Story />
+      </ShadowDomWrapper>
+    ),
  withScrollingSwitcher,
  ...(process.env.NODE_ENV !== 'production' ? [withStrictModeSwitcher] : []),
  withProviderSwitcher
];

🧢 Your Project:

PSPDFKit -

[ritz078]

@snowystinger We are working on fixing the linting and type errors but if you want you can give an early eye to this PR.

[snowystinger]

perf and size comments on PR #7548 (comment)

[ritz078]

would you mind testing the new changes in your application and let us know if they still work for you

@snowystinger These changes look good so far. Our internal tests are passing. We will be opening some small followup PRs too once this gets merged. Any idea about the timeline for this PR ?

[snowystinger]

Thanks for checking in, we are still in discussions internally. Should have more information for you early next week.

[devongovett]

Thanks for working on this. I appreciate the persistence, and I know it's been a long process.

In the future, I think we may need to revisit how some of our components are implemented more holistically to account for shadow dom. While deeply traversing into shadow roots works in some cases, it won't work with closed shadow roots. For example, even with the FocusScope changes here, things like native <video> elements, <input type="date">, etc., along with any third party components using closed shadow roots will still not work correctly since we cannot traverse into them. Fixing that would require a completely different implementation strategy.

Overall, shadow dom is meant to encapsulate behavior, and deep traversal sort of goes against that goal. For now it's better than nothing, but it would be good to try to find ways to avoid it in the future if possible.

[snowystinger]

Thanks again, this will be available in our nightlies starting tonight. You can enable the behavior using the feature flag.

import {enableShadowDOM} from '@react-stately/flags';

As @devongovett noted, we're starting to think about how we want to move forward with this kind of work. We've made a start here: #7687
Feel free to add your voice as well. We're still building up the requirements and it helps to have real life cases to draw from.