feat: add helper functions and docs (microsoft#29506)

Adds helper functions to simplify working with `merge-styles`
shadow DOM APIs.

Adds documentation explaining basic usage of shadow DOM features.

packages/merge-styles/README.md

@@ -504,3 +504,75 @@ window.FabricConfig = {
  },
 };
 ```
+
+## Shadow DOM
+
+`merge-styles` has experimental 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 to 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 { useWindow } from '@fluentui/react';
+import { mergeStyles } from '@fluentui/merge-styles';
+import { useShadowConfig, useAdoptedStylesheet } from '@fluentui/utilities';
+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 => {
+ // 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);
+};
+```

packages/merge-styles/etc/merge-styles.api.md

@@ -469,6 +469,9 @@ export interface IStyleSheetConfig {
 // @public
 export function keyframes(timeline: IKeyframes): string;
 
+// @public (undocumented)
+export const makeShadowConfig: (stylesheetKey: string, inShadow: boolean, window?: Window) => ShadowConfig;
+
 // Warning: (ae-forgotten-export) The symbol "IStyleOptions" needs to be exported by the entry point index.d.ts
 //
 // @public

packages/merge-styles/src/index.ts

@@ -39,7 +39,7 @@ export { setRTL } from './StyleOptionsState';
 
 export type { ObjectOnly } from './ObjectOnly';
 
-export { GLOBAL_STYLESHEET_KEY } from './shadowConfig';
+export { GLOBAL_STYLESHEET_KEY, makeShadowConfig } from './shadowConfig';
 export type { ShadowConfig } from './shadowConfig';
 
 import './version';

packages/merge-styles/src/shadowConfig.ts

@@ -14,6 +14,15 @@ export const DEFAULT_SHADOW_CONFIG: ShadowConfig = {
  __isShadowConfig__: true,
 } as const;
 
+export const makeShadowConfig = (stylesheetKey: string, inShadow: boolean, window?: Window): ShadowConfig => {
+ return {
+ stylesheetKey,
+ inShadow,
+ window,
+ __isShadowConfig__: true,
+ };
+};
+
 export const isShadowConfig = (obj: unknown): obj is ShadowConfig => {
  if (!obj) {
  return false;

packages/utilities/src/customizations/customizable.tsx

@@ -2,7 +2,7 @@ import * as React from 'react';
 import { Customizations } from './Customizations';
 import { hoistStatics } from '../hoistStatics';
 import { CustomizerContext } from './CustomizerContext';
-import { concatStyleSets } from '@fluentui/merge-styles';
+import { concatStyleSets, makeShadowConfig } from '@fluentui/merge-styles';
 import type { ICustomizerContext } from './CustomizerContext';
 import { MergeStylesShadowRootConsumer } from '../shadowDom/MergeStylesShadowRootContext';
 import type { ShadowConfig } from '@fluentui/merge-styles';
@@ -56,14 +56,8 @@ export function customizable(
  this._shadowConfig.stylesheetKey !== scope ||
  this._shadowConfig.inShadow !== inShadow ||
  this._shadowConfig.window !== win
- // false
  ) {
- this._shadowConfig = {
- stylesheetKey: scope,
- inShadow,
- window: win,
- __isShadowConfig__: true,
- };
+ this._shadowConfig = makeShadowConfig(scope, inShadow, win);
  }
 
  // eslint-disable-next-line @typescript-eslint/no-explicit-any

packages/utilities/src/shadowDom/MergeStylesRootContext.tsx

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { GLOBAL_STYLESHEET_KEY, Stylesheet } from '@fluentui/merge-styles';
+import { GLOBAL_STYLESHEET_KEY, Stylesheet, makeShadowConfig } from '@fluentui/merge-styles';
 import { getWindow } from '../dom';
 
 declare global {
@@ -82,12 +82,8 @@ export const MergeStylesRootProvider: React.FC<MergeStylesRootProviderProps> = (
 
  let changed = false;
  const next = new Map<string, CSSStyleSheet>(stylesheets);
- const sheet = Stylesheet.getInstance({
- window: win,
- inShadow: false,
- stylesheetKey: GLOBAL_STYLESHEET_KEY,
- __isShadowConfig__: true,
- });
+ const sheet = Stylesheet.getInstance(makeShadowConfig(GLOBAL_STYLESHEET_KEY, false, win));
+
  sheet.forEachAdoptedStyleSheet((adoptedSheet, key) => {
  next.set(key, adoptedSheet);
  changed = true;

packages/utilities/src/shadowDom/MergeStylesShadowRootContext.tsx

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { GLOBAL_STYLESHEET_KEY } from '@fluentui/merge-styles';
+import { GLOBAL_STYLESHEET_KEY, makeShadowConfig } from '@fluentui/merge-styles';
 import { FocusRectsProvider } from '../FocusRectsProvider';
 import { useMergeStylesRootStylesheets } from './MergeStylesRootContext';
 
@@ -80,7 +80,6 @@ const GlobalStyles: React.FC = props => {
 export const useAdoptedStylesheet = (stylesheetKey: string): boolean => {
  const shadowCtx = useMergeStylesShadowRootContext();
  const rootMergeStyles = useMergeStylesRootStylesheets();
- // console.log('useAdoptedStylesheets', stylesheetKey);
 
  if (!shadowCtx) {
  return false;
@@ -112,3 +111,16 @@ export const useHasMergeStylesShadowRootContext = () => {
 export const useMergeStylesShadowRootContext = () => {
  return React.useContext(MergeStylesShadowRootContext);
 };
+
+/**
+ * Get a shadow config.
+ * @param stylesheetKey - Globally unique key
+ * @param win - Reference to the `window` global.
+ * @returns ShadowConfig
+ */
+export const useShadowConfig = (stylesheetKey: string, win?: Window) => {
+ const inShadow = useHasMergeStylesShadowRootContext();
+ return React.useMemo(() => {
+ return makeShadowConfig(stylesheetKey, inShadow, win);
+ }, [stylesheetKey, inShadow, win]);
+};

packages/utilities/src/styled.tsx

@@ -1,6 +1,6 @@
 import * as React from 'react';
 import { concatStyleSetsWithProps } from '@fluentui/merge-styles';
-import { useAdoptedStylesheet, useHasMergeStylesShadowRootContext } from './shadowDom/MergeStylesShadowRootContext';
+import { useAdoptedStylesheet, useShadowConfig } from './shadowDom/MergeStylesShadowRootContext';
 import { useCustomizationSettings } from './customizations/useCustomizationSettings';
 import type { IStyleSet, IStyleFunctionOrObject, ShadowConfig } from '@fluentui/merge-styles';
 import { getWindow } from './dom/getWindow';
@@ -103,21 +103,7 @@ export function styled<
  const additionalProps = getProps ? getProps(props) : undefined;
 
  const win = useWindow() ?? getWindow();
-
- const inShadow = useHasMergeStylesShadowRootContext();
- const shadowConfig = React.useRef<ShadowConfig>({ stylesheetKey: scope, inShadow, __isShadowConfig__: true });
- if (
- shadowConfig.current.stylesheetKey !== scope ||
- shadowConfig.current.inShadow !== inShadow ||
- shadowConfig.current.window !== win
- ) {
- shadowConfig.current = {
- stylesheetKey: scope,
- inShadow,
- window: win,
- __isShadowConfig__: true,
- };
- }
+ const shadowConfig = useShadowConfig(scope, win);
 
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  const cache = (styles.current && (styles.current as any).__cachedInputs__) || [];
@@ -143,7 +129,7 @@ export function styled<
  styles.current = concatenatedStyles as StyleFunction<TStyleProps, TStyleSet>;
  }
 
- styles.current.__shadowConfig__ = shadowConfig.current;
+ styles.current.__shadowConfig__ = shadowConfig;
 
  useAdoptedStylesheet(scope);