@servicetitan/web-components 36.3.0 → 36.4.0

package/src/css-injector/__tests__/with-css-injector.test.tsx

@@ -0,0 +1,128 @@
+import { render } from '@testing-library/react';
+import { FC } from 'react';
+import { useMFEMetadataContext } from '../../contexts/mfe-metadata-context';
+import { MfeStyleRegistry } from '../mfe-style-registry';
+import { withCssInjector } from '../with-css-injector';
+
+jest.mock('../../contexts/mfe-metadata-context');
+jest.mock('../../globals', () => ({
+    // eslint-disable-next-line @typescript-eslint/naming-convention
+    WEB_COMPONENT_NAME: 'test-mfe',
+}));
+jest.mock('../mfe-style-registry');
+
+describe(`[web-components] ${withCssInjector.name}`, () => {
+    const innerTestId = 'inner';
+    const innerLabel = 'foo';
+    const InnerComponent: FC<{ label: string }> = ({ label }) => (
+        <div data-testid={innerTestId}>{label}</div>
+    );
+    const WrappedComponent = withCssInjector(InnerComponent);
+
+    let registry: jest.Mocked<MfeStyleRegistry>;
+    let shadowRoot: ShadowRoot;
+    let portalShadowRoot: ShadowRoot;
+
+    beforeEach(() => {
+        jest.clearAllMocks();
+        delete globalThis.__mfeSelfHosted__;
+        registry = {
+            observeRoot: jest.fn(),
+            unobserveRoot: jest.fn(),
+        } as unknown as jest.Mocked<MfeStyleRegistry>;
+        jest.mocked(MfeStyleRegistry.for).mockReturnValue(registry);
+        shadowRoot = document.createElement('div').attachShadow({ mode: 'open' });
+        portalShadowRoot = document.createElement('span').attachShadow({ mode: 'open' });
+        jest.mocked(useMFEMetadataContext).mockImplementation(() => ({
+            shadowRoot,
+            portalShadowRoot,
+        }));
+    });
+
+    const subject = () => render(<WrappedComponent label={innerLabel} />);
+
+    test('renders the wrapped component with its props', () => {
+        const { getByTestId } = subject();
+
+        expect(getByTestId(innerTestId).textContent).toBe(innerLabel);
+    });
+
+    test('retrieves the registry for the component', () => {
+        subject();
+
+        expect(MfeStyleRegistry.for).toHaveBeenCalledWith('test-mfe');
+    });
+
+    test('observes shadow root', () => {
+        subject();
+
+        expect(registry.observeRoot).toHaveBeenCalledWith(shadowRoot);
+    });
+
+    test('observes portal shadow root', () => {
+        subject();
+
+        expect(registry.observeRoot).toHaveBeenCalledWith(portalShadowRoot);
+    });
+
+    describe('when self-hosted', () => {
+        beforeEach(() => {
+            globalThis.__mfeSelfHosted__ = true;
+        });
+
+        test('observes document', () => {
+            subject();
+
+            expect(registry.observeRoot).toHaveBeenCalledWith(document);
+        });
+
+        test('unobserves document on unmount', () => {
+            const { unmount } = subject();
+
+            unmount();
+
+            expect(registry.unobserveRoot).toHaveBeenCalledWith(document);
+        });
+    });
+
+    describe('when unmounted', () => {
+        test('unobserves shadow root', () => {
+            const { unmount } = subject();
+
+            unmount();
+
+            expect(registry.unobserveRoot).toHaveBeenCalledWith(shadowRoot);
+        });
+
+        test('unobserves portal shadow root', () => {
+            const { unmount } = subject();
+
+            unmount();
+
+            expect(registry.unobserveRoot).toHaveBeenCalledWith(portalShadowRoot);
+        });
+    });
+
+    describe('in production', () => {
+        const originalEnv = process.env.NODE_ENV;
+
+        beforeEach(() => {
+            process.env.NODE_ENV = 'production';
+        });
+
+        afterEach(() => {
+            process.env.NODE_ENV = originalEnv;
+        });
+
+        test('returns Component directly', () => {
+            expect.assertions(1);
+
+            jest.isolateModules(() => {
+                const { withCssInjector: freshWithCssInjector } = require('../with-css-injector');
+                const Dummy: FC = () => <div />;
+
+                expect(freshWithCssInjector(Dummy)).toBe(Dummy);
+            });
+        });
+    });
+});

package/src/css-injector/index.ts

@@ -0,0 +1,2 @@
+export { MfeStyleRegistry } from './mfe-style-registry';
+export { withCssInjector } from './with-css-injector';

package/src/css-injector/mfe-style-registry.ts

@@ -0,0 +1,48 @@
+declare global {
+    // eslint-disable-next-line @typescript-eslint/naming-convention
+    var __mfeStyles__: Record<string, MfeStyleRegistry> | undefined;
+}
+
+type StyleRoot = ShadowRoot | Document;
+
+export class MfeStyleRegistry {
+    readonly sheets = new Map<string, CSSStyleSheet>();
+    readonly roots = new Set<StyleRoot>();
+
+    // Per-component state stored on globalThis.__mfeStyles__ so it survives Vite HMR module reloads.
+    static for(componentName: string): MfeStyleRegistry {
+        globalThis.__mfeStyles__ ??= {};
+        globalThis.__mfeStyles__[componentName] ??= new MfeStyleRegistry();
+        return globalThis.__mfeStyles__[componentName];
+    }
+
+    injectSheet(sheetId: string, css: string) {
+        let sheet = this.sheets.get(sheetId);
+        if (sheet) {
+            sheet.replaceSync(css);
+        } else {
+            sheet = new CSSStyleSheet();
+            sheet.replaceSync(css);
+            this.sheets.set(sheetId, sheet);
+            for (const root of this.roots) {
+                root.adoptedStyleSheets = [...root.adoptedStyleSheets, sheet];
+            }
+        }
+    }
+
+    observeRoot(root: StyleRoot) {
+        if (this.roots.has(root)) {
+            return;
+        }
+        this.roots.add(root);
+        root.adoptedStyleSheets ??= [];
+        root.adoptedStyleSheets = [...root.adoptedStyleSheets, ...this.sheets.values()];
+    }
+
+    unobserveRoot(root: StyleRoot) {
+        this.roots.delete(root);
+        const sheets = new Set(this.sheets.values());
+        root.adoptedStyleSheets ??= [];
+        root.adoptedStyleSheets = root.adoptedStyleSheets.filter(s => !sheets.has(s));
+    }
+}

package/src/css-injector/with-css-injector.tsx

@@ -0,0 +1,40 @@
+import { ComponentType, useLayoutEffect } from 'react';
+import { useMFEMetadataContext } from '../contexts/mfe-metadata-context';
+import { WEB_COMPONENT_NAME } from '../globals';
+import { MfeStyleRegistry } from './mfe-style-registry';
+
+declare global {
+    // eslint-disable-next-line @typescript-eslint/naming-convention
+    var __mfeSelfHosted__: boolean | undefined;
+}
+
+/*
+ * HOC wrapping the MFE's root component in register(). Adopts sheets from the registry into
+ * the MFE's shadow roots. Only active in development; eliminated by Vite in production builds.
+ */
+export function withCssInjector<P extends object>(Component: ComponentType<P>): ComponentType<P> {
+    if (process.env.NODE_ENV === 'production') {
+        return Component;
+    }
+
+    return function CssInjectorWrapper(props: P) {
+        const { shadowRoot, portalShadowRoot } = useMFEMetadataContext();
+
+        useLayoutEffect(() => {
+            const registry = MfeStyleRegistry.for(WEB_COMPONENT_NAME);
+            const roots = [
+                shadowRoot,
+                portalShadowRoot,
+                ...(globalThis.__mfeSelfHosted__ ? [document] : []),
+            ];
+
+            roots.forEach(root => registry.observeRoot(root));
+
+            return () => {
+                roots.forEach(root => registry.unobserveRoot(root));
+            };
+        }, [shadowRoot, portalShadowRoot]);
+
+        return <Component {...props} />;
+    };
+}

package/src/globals.ts

@@ -1,4 +1,6 @@
 /* eslint-disable @typescript-eslint/naming-convention */
+// eslint-disable-next-line spaced-comment
+/// <reference types="vite/client" /> — provides types for import.meta.env
 import { ExposedDependencies } from '@servicetitan/startup-utils';
 import { ExposedInstanceDependencies } from './common';
 
@@ -8,6 +10,13 @@ declare global {
     export const WEB_COMPONENT_NAME: string | undefined;
 }
 
+/*
+ * Safely access a value that may not exist. Returns undefined instead of
+ * throwing a ReferenceError. Used below to try global constants first
+ * (set by webpack DefinePlugin), then fall back to import.meta.env
+ * (set by Vite's define config). One of these will always be defined
+ * depending on which bundler built the code.
+ */
 function get<T>(fetch: () => T) {
     try {
         return fetch();
@@ -16,17 +25,28 @@ function get<T>(fetch: () => T) {
     }
 }
 
-const _EXPOSED_DEPENDENCIES = get(() => {
-    return EXPOSED_DEPENDENCIES;
-});
+const _EXPOSED_DEPENDENCIES =
+    get(() => {
+        return EXPOSED_DEPENDENCIES;
+    }) ??
+    get(() => {
+        return import.meta.env.EXPOSED_DEPENDENCIES;
+    });
 
-const _WEB_COMPONENT_NAME = get(() => {
-    return WEB_COMPONENT_NAME;
-});
-
-const _EXPOSED_INSTANCE_DEPENDENCIES = get(() => {
-    return EXPOSED_INSTANCE_DEPENDENCIES;
-});
+const _WEB_COMPONENT_NAME =
+    get(() => {
+        return WEB_COMPONENT_NAME;
+    }) ??
+    get(() => {
+        return import.meta.env.WEB_COMPONENT_NAME;
+    });
+const _EXPOSED_INSTANCE_DEPENDENCIES =
+    get(() => {
+        return EXPOSED_INSTANCE_DEPENDENCIES;
+    }) ??
+    get(() => {
+        return import.meta.env.EXPOSED_INSTANCE_DEPENDENCIES;
+    });
 
 export {
     _EXPOSED_DEPENDENCIES as EXPOSED_DEPENDENCIES,

package/src/index.ts

@@ -1,5 +1,6 @@
 export * from './common';
 export * from './contexts';
+export * from './css-injector';
 export * from './event-bus';
 export * from './get-value-for-environment';
 export * from './headless-loader';

package/src/register-headless.ts

@@ -2,6 +2,7 @@ import type { LDService } from '@servicetitan/launchdarkly-service';
 import type { Log } from '@servicetitan/log-service';
 import type { Entries, IWebComponent } from './common';
 import type { EventBus } from './event-bus';
+import { WEB_COMPONENT_NAME } from './globals';
 import { Serializable } from './types';
 
 type HeadlessCallbackArgs<TMfeData, TEventBus extends EventBus = EventBus> = Pick<

package/src/register.tsx

@@ -2,7 +2,7 @@ import { type LDService } from '@servicetitan/launchdarkly-service';
 import { Log } from '@servicetitan/log-service';
 import { Provider } from '@servicetitan/react-ioc';
 import { ExposedDependencies } from '@servicetitan/startup-utils';
-import { ComponentType, FC, ReactElement, useEffect } from 'react';
+import { ComponentType, FC, PropsWithChildren, ReactElement, useCallback, useEffect } from 'react';
 import {
     BASENAME_TOKEN,
     Entries,
@@ -15,6 +15,7 @@ import {
 } from './common';
 import { MFEDataContext } from './contexts/mfe-data-context';
 import { MFEMetadataContext } from './contexts/mfe-metadata-context';
+import { withCssInjector } from './css-injector';
 import { EVENT_BUS_TOKEN, EventBus } from './event-bus';
 import { WEB_COMPONENT_NAME } from './globals';
 import { HistoryManager } from './history-manager';
@@ -40,7 +41,50 @@ export interface RegisterOptions {
     sharedDependenciesNames?: string[];
 }
 
+const Anvil1Providers: FC<{ root: ShadowRoot; portal: ShadowRoot } & PropsWithChildren> = ({
+    root,
+    portal,
+    children,
+}) => {
+    const getTablePopupProps = useCallback(
+        (props: object) => ({
+            ...props,
+            appendTo: root as unknown as HTMLElement,
+        }),
+        [root]
+    );
+
+    try {
+        const { DefaultPortalContext, TablePopupPropsContext } =
+            require('@servicetitan/design-system') as typeof import('@servicetitan/design-system');
+        return (
+            <DefaultPortalContext.Provider value={portal as unknown as HTMLElement}>
+                <TablePopupPropsContext.Provider value={getTablePopupProps}>
+                    {children}
+                </TablePopupPropsContext.Provider>
+            </DefaultPortalContext.Provider>
+        );
+    } catch {
+        return children;
+    }
+};
+
+const Anvil2Providers: FC<{ portalAnvilContainer: HTMLDivElement } & PropsWithChildren> = ({
+    portalAnvilContainer,
+    children,
+}) => {
+    try {
+        const { PortalProvider } =
+            require('@servicetitan/anvil2') as typeof import('@servicetitan/anvil2');
+        return <PortalProvider root={portalAnvilContainer}>{children}</PortalProvider>;
+    } catch {
+        return children;
+    }
+};
+
 export function register(Component: ComponentType, light: boolean, options?: RegisterOptions) {
+    const WrappedComponent = withCssInjector(Component);
+
     class WebComponent extends HTMLElement implements IWebComponent {
         private root?: ShadowRoot;
         private portal?: ShadowRoot;
@@ -165,47 +209,14 @@ export function register(Component: ComponentType, light: boolean, options?: Reg
             return elements;
         };
 
-        private withAnvil1Providers(children: ReactElement): ReactElement {
-            try {
-                /**
-                 * Note, the webpack.IgnorePlugin must be configured to ignore this dependency.
-                 * @see {@link file://./../../startup/src/webpack/configs/plugins/ignore-plugin/ignore-plugin.ts}
-                 */
-                const { DefaultPortalContext, TablePopupPropsContext } =
-                    require('@servicetitan/design-system') as typeof import('@servicetitan/design-system');
-                return (
-                    <DefaultPortalContext.Provider value={this.portal as unknown as HTMLElement}>
-                        <TablePopupPropsContext.Provider
-                            value={props => ({
-                                ...props,
-                                appendTo: this.root as unknown as HTMLElement,
-                            })}
-                        >
-                            {children}
-                        </TablePopupPropsContext.Provider>
-                    </DefaultPortalContext.Provider>
-                );
-            } catch {
-                return children;
-            }
-        }
-
-        private withAnvil2Providers(children: ReactElement): ReactElement {
-            try {
-                /**
-                 * Note, the webpack.IgnorePlugin must be configured to ignore this dependency.
-                 * @see {@link file://./../../startup/src/webpack/configs/plugins/ignore-plugin/ignore-plugin.ts}
-                 */
-                const { PortalProvider } =
-                    require('@servicetitan/anvil2') as typeof import('@servicetitan/anvil2');
-                return <PortalProvider root={this.portalAnvilContainer}>{children}</PortalProvider>;
-            } catch {
-                return children;
-            }
-        }
-
-        private withProviders(children: ReactElement): ReactElement {
-            return this.withAnvil2Providers(this.withAnvil1Providers(children));
+        private withProviders(children: ReactElement) {
+            return (
+                <Anvil2Providers portalAnvilContainer={this.portalAnvilContainer!}>
+                    <Anvil1Providers root={this.root!} portal={this.portal!}>
+                        {children}
+                    </Anvil1Providers>
+                </Anvil2Providers>
+            );
         }
 
         private render = () => {
@@ -264,7 +275,7 @@ export function register(Component: ComponentType, light: boolean, options?: Reg
                         >
                             <MFEDataContext.Provider value={{ ...mfeData }}>
                                 <MFEMetadataContext.Provider value={metadata}>
-                                    {this.withProviders(<Component {...mfeData} />)}
+                                    {this.withProviders(<WrappedComponent {...mfeData} />)}
                                     {this.onReady && <RenderCallback callback={this.onReady} />}
                                 </MFEMetadataContext.Provider>
                             </MFEDataContext.Provider>

package/src/render.ts

@@ -6,14 +6,13 @@ import type ReactDOMClient from 'react-dom/client';
 let createRoot: typeof ReactDOMClient.createRoot;
 try {
     /**
-     * Note, the webpack.IgnorePlugin must be configured to ignore this dependency.
-     * @see {@link file://./../../startup/src/webpack/configs/plugins/ignore-plugin/ignore-plugin.ts}
+     * Note, bundlers must be configured to ignore this dependency.
+     * @see {@link file://./../../startup/src/core/check-resource/is-managed-react-dom-client-dependency.ts}
      */
     createRoot = require('react-dom/client').createRoot;
 } catch {
     // ignore
 }
-
 interface RenderOptions {
     legacyRoot?: boolean;
 }

package/src/utils/get-bundle-info.ts

@@ -78,14 +78,13 @@ export async function getBundleInfo({
         resolvedBundleType = embed ? 'light' : 'full';
     }
 
-    const withBaseUrl = (path: string) =>
-        `${exactPackageUrl}/dist/bundle/${resolvedBundleType}/${path}`;
+    const bundleBaseUrl = `${exactPackageUrl}/dist/bundle/${resolvedBundleType}`;
 
     let entrypoints: EntryPoints;
     if (metadata.entrypoints?.[resolvedBundleType]) {
         entrypoints = metadata.entrypoints[resolvedBundleType];
     } else {
-        entrypoints = await getEntrypoints(withBaseUrl('entrypoints.json'), requestCache);
+        entrypoints = await getEntrypoints(`${bundleBaseUrl}/entrypoints.json`, requestCache);
     }
 
     const disposer = () => {
@@ -97,9 +96,17 @@ export async function getBundleInfo({
         }
     };
 
+    let baseUrl = bundleBaseUrl;
+    // Per-MFE dev-server port only happens during local development
+    if (process.env.NODE_ENV !== 'production' && entrypoints.port) {
+        const url = new URL(baseUrl);
+        url.port = String(entrypoints.port);
+        baseUrl = url.toString();
+    }
+
     const urls: EntryPoints = {
-        css: entrypoints.css.map(withBaseUrl),
-        js: entrypoints.js.map(withBaseUrl),
+        css: entrypoints.css.map(path => `${baseUrl}/${path}`),
+        js: entrypoints.js.map(path => `${baseUrl}/${path}`),
     };
 
     const elementName = resolvedBundleType === 'headless' ? `headless-${name}` : name;

package/src/utils/get-entry-points.ts

@@ -4,6 +4,7 @@ export interface EntryPoints {
     css: string[];
     js: string[];
     module?: true;
+    port?: number;
 }
 
 export async function getEntrypoints(