Add shadow DOM support to @fluentui/react (Fluent v8)

apps/stress-test/src/renderers/wc/btn/wcBasicButton.ts

@@ -2,13 +2,11 @@ import { DOMSelectorTreeComponentRenderer } from '../../../shared/vanilla/types'
 
 declare global {
   interface Document {
-    // eslint-disable-next-line
-    adoptedStyleSheets: any[];
+    adoptedStyleSheets: CSSStyleSheet[];
   }
 
   interface ShadowRoot {
-    // eslint-disable-next-line
-    adoptedStyleSheets: any[];
+    adoptedStyleSheets: CSSStyleSheet[];
   }
 
   interface CSSStyleSheet {

change/@fluentui-dom-utilities-781d59ca-cc21-4853-8971-45459939f85d.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "feat: add shadow DOM support for DOM APIs",
+  "packageName": "@fluentui/dom-utilities",
+  "email": "seanmonahan@microsoft.com",
+  "dependentChangeType": "patch"
+}

change/@fluentui-jest-serializer-merge-styles-8ad53e9f-3456-4924-b50d-48ffd979b2ce.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "chore: add typescript types",
+  "packageName": "@fluentui/jest-serializer-merge-styles",
+  "email": "seanmonahan@microsoft.com",
+  "dependentChangeType": "patch"
+}

change/@fluentui-merge-styles-284eeed7-0d8c-4ebf-a44c-1e34467aca9b.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "feat: add support for shadow dom and constructable stylesheets",
+  "packageName": "@fluentui/merge-styles",
+  "email": "seanmonahan@microsoft.com",
+  "dependentChangeType": "patch"
+}

change/@fluentui-react-b73398fa-9e0a-4d05-97a4-7a4820a876c1.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "feat: update some components to optionally support shadow dom",
+  "packageName": "@fluentui/react",
+  "email": "seanmonahan@microsoft.com",
+  "dependentChangeType": "patch"
+}

change/@fluentui-react-focus-a8531b74-9b98-4cb7-8806-cae9890d42ed.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "feat: add shadow DOM support when traversing the DOM",
+  "packageName": "@fluentui/react-focus",
+  "email": "seanmonahan@microsoft.com",
+  "dependentChangeType": "patch"
+}

change/@fluentui-react-hooks-2a9a3785-211f-4a01-8343-0dec3306fc82.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "feat: add support for shadow roots",
+  "packageName": "@fluentui/react-hooks",
+  "email": "seanmonahan@microsoft.com",
+  "dependentChangeType": "patch"
+}

change/@fluentui-style-utilities-febc26a4-57df-4d2a-b99f-b4d43752dd6e.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "feat: add support for shadow dom and constructable stylesheets",
+  "packageName": "@fluentui/style-utilities",
+  "email": "seanmonahan@microsoft.com",
+  "dependentChangeType": "patch"
+}

change/@fluentui-utilities-3b3cdc9c-0e4f-4c68-aee6-9040e041186c.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "feat: add support for shadow dom and constructable stylesheets",
+  "packageName": "@fluentui/utilities",
+  "email": "seanmonahan@microsoft.com",
+  "dependentChangeType": "patch"
+}

packages/dom-utilities/etc/dom-utilities.api.md

@@ -16,9 +16,15 @@ export function elementContainsAttribute(element: HTMLElement, attribute: string
 // @public
 export function findElementRecursive(element: HTMLElement | null, matchFunction: (element: HTMLElement) => boolean, doc?: Document): HTMLElement | null;
 
+// @public (undocumented)
+export const getActiveElement: (doc: Document) => Element | null;
+
 // @public
 export function getChildren(parent: HTMLElement, allowVirtualChildren?: boolean): HTMLElement[];
 
+// @public (undocumented)
+export const getEventTarget: (event: Event) => HTMLElement | null;
+
 // @public
 export function getParent(child: HTMLElement, allowVirtualParents?: boolean): HTMLElement | null;
 

packages/dom-utilities/src/getActiveElement.ts

@@ -0,0 +1,9 @@
+export const getActiveElement = (doc: Document): Element | null => {
+  let ae = doc.activeElement;
+
+  while (ae?.shadowRoot) {
+    ae = ae.shadowRoot.activeElement;
+  }
+
+  return ae;
+};

packages/dom-utilities/src/getEventTarget.ts

@@ -0,0 +1,8 @@
+export const getEventTarget = (event: Event): HTMLElement | null => {
+  let target = event.target as HTMLElement;
+  if (target && target.shadowRoot) {
+    target = event.composedPath()[0] as HTMLElement;
+  }
+
+  return target;
+};

packages/dom-utilities/src/getParent.ts

@@ -7,8 +7,25 @@ import { getVirtualParent } from './getVirtualParent';
  * @public
  */
 export function getParent(child: HTMLElement, allowVirtualParents: boolean = true): HTMLElement | null {
-  return (
-    child &&
-    ((allowVirtualParents && getVirtualParent(child)) || (child.parentNode && (child.parentNode as HTMLElement)))
-  );
+  if (!child) {
+    return null;
+  }
+
+  const parent = allowVirtualParents && getVirtualParent(child);
+
+  if (parent) {
+    return parent;
+  }
+
+  // Support looking for parents in shadow DOM
+  if (typeof (child as HTMLSlotElement).assignedElements !== 'function' && child.assignedSlot?.parentNode) {
+    // Element is slotted
+    return child.assignedSlot as HTMLElement;
+  } else if (child.parentNode?.nodeType === 11) {
+    // nodeType 11 is DOCUMENT_FRAGMENT
+    // Element is in shadow root
+    return (child.parentNode as ShadowRoot).host as HTMLElement;
+  } else {
+    return child.parentNode as HTMLElement;
+  }
 }

packages/dom-utilities/src/index.ts

@@ -1,13 +1,15 @@
-export * from './IVirtualElement';
-export * from './elementContains';
-export * from './elementContainsAttribute';
-export * from './findElementRecursive';
-export * from './getChildren';
-export * from './getParent';
-export * from './getVirtualParent';
-export * from './isVirtualElement';
-export * from './portalContainsElement';
-export * from './setPortalAttribute';
-export * from './setVirtualParent';
+export type { IVirtualElement } from './IVirtualElement';
+export { elementContains } from './elementContains';
+export { elementContainsAttribute } from './elementContainsAttribute';
+export { findElementRecursive } from './findElementRecursive';
+export { getActiveElement } from './getActiveElement';
+export { getChildren } from './getChildren';
+export { getEventTarget } from './getEventTarget';
+export { getParent } from './getParent';
+export { getVirtualParent } from './getVirtualParent';
+export { isVirtualElement } from './isVirtualElement';
+export { portalContainsElement } from './portalContainsElement';
+export { DATA_PORTAL_ATTRIBUTE, setPortalAttribute } from './setPortalAttribute';
+export { setVirtualParent } from './setVirtualParent';
 
 import './version';

packages/jest-serializer-merge-styles/tsconfig.json

@@ -3,7 +3,7 @@
     "target": "es5",
     "outDir": "lib",
     "module": "commonjs",
-    "lib": ["es2017"],
+    "lib": ["es2017", "dom"],
     "jsx": "react",
     "declaration": true,
     "sourceMap": true,

packages/merge-styles/README.md

@@ -504,3 +504,76 @@ window.FabricConfig = {
   },
 };
 ```
+
+## Shadow DOM
+
+`merge-styles` has support for [shadow DOM](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM). This feature is opt-in and incrementally adoptable. To enable the feature you need to include two [React Providers](https://react.dev/reference/react/createContext#provider):
+
+1. `MergeStylesRootProvider`: acts as the "global" context for your application. You should have one of these per page.
+2. `MergeStylesShadowRootProvider`: a context for each shadow root in your application. You should have one of these per shadow root.
+
+`merge-styles` does not provide an option for creating shadow roots in React as how you get a shadow root doesn't matter, just that you have a reference to one. [`react-shadow`](https://www.npmjs.com/package/react-shadow) is one library that can create shadow roots in React and will be used in examples.
+
+### Shadow DOM example
+
+```tsx
+import { PrimaryButton } from '@fluentui/react';
+import { MergeStylesRootProvider, MergeStylesShadowRootProvider } from '@fluentui/utilities';
+import root from 'react-shadow';
+
+const ShadowRoot = ({ children }) => {
+  // This is a ref but we're using state to manage it so we can force
+  // a re-render.
+  const [shadowRootEl, setShadowRootEl] = React.useState<HTMLElement | null>(null);
+
+  return (
+    <MergeStylesRootProvider>
+      <root.div className="shadow-root" delegatesFocus ref={setShadowRootEl}>
+        <MergeStylesShadowRootProvider shadowRoot={shadowRootEl?.shadowRoot}>{children}</MergeStylesShadowRootProvider>
+      </root.div>
+    </MergeStylesRootProvider>
+  );
+};
+
+<ShadowRoot>
+  <PrimaryButton>I'm in the shadow DOM!</PrimaryButton>
+</ShadowRoot>
+<PrimaryButton>I'm in the light DOM!</PrimaryButton>
+```
+
+### Scoping styles for more efficient CSS
+
+You do not _need_ to update your `merge-styles` styles to support shadow DOM but you can make styles more efficient with some updates.
+
+Shadow DOM support is achieved in `merge-styles` by using [constructable stylesheets](https://web.dev/articles/constructable-stylesheets) and is scoped by "stylesheet keys". `merge-styles` creates one stylesheet per key and in Fluent this means each component has its own stylesheet. Each `MergeStylesShadowRootProvider` will only adopt styles for components it contains plus the global sheet (we cannot be certain whether we need this sheet or not so we always adopt it). This means a `MergeStylesShadowRootProvider` that contains a button will only adopt button styles (plus the global styles) but not checkbox styles, making styling within the shadow root more efficient.
+
+If you use `customizable` or `styled` the existing "scope" value provided to these functions is used a unique key. If no key is provided `merge-styles` falls back to a "global" key. This global key is a catch-all and allows us to support code that was written before shadow DOM support was added or code that is called outside of React context.
+
+All `@fluentui/react` styles are scoped via `customizable` and `styled` (and some updates to specific component styles where needed). If your components use these functions and you set the "scope" property your components will automatically be scoped.
+If you're using `mergeStyles()` (and other `merge-styles` APIs) directly, your styles will be placed in the global scope and still be available in shadow roots, just not as optimally as possible.
+
+#### Style scoping example
+
+```tsx
+import { useMergeStylesHooks } from '@fluentui/react';
+import { mergeStyles } from '@fluentui/merge-styles';
+import type { ShadowConfig } from '@fluentui/merge-styles';
+
+// This must be globally unique for the application
+const MY_COMPONENT_STYLESHEET_KEY: string = 'my-unique-key';
+
+const MyComponent = props => {
+  const { useWindow, useShadowConfig, useAdoptedStylesheet } = useMergeStylesHooks();
+
+  // Make sure multi-window scenarios work (e.g., pop outs)
+  const win: Window = useWindow();
+  const shadowConfig: ShadowConfig = useShadowConfig(MY_COMPONENT_STYLESHEET_KEY, win);
+
+  const styles = React.useMemo(() => {
+    // shadowConfig must be the first parameter when it is used
+    return mergeStyles(shadowConfig, myStyles);
+  }, [shadowConfig, myStyles]);
+
+  useAdoptedStylesheet(MY_COMPONENT_STYLESHEET_KEY);
+};
+```