@servicetitan/web-components 31.0.0 → 31.2.0

package/src/__tests__/headless-loader.test.tsx

@@ -0,0 +1,123 @@
+import '@testing-library/jest-dom';
+import { act, render, waitFor } from '@testing-library/react';
+import * as common from '../common';
+import { HeadlessLoader } from '../headless-loader';
+
+describe('[web-components] HeadlessLoader', () => {
+    class Page {
+        static get webComponent() {
+            return document.querySelector(`headless-${WEB_COMPONENT_NAME}`);
+        }
+    }
+
+    class WebComponent extends HTMLElement {
+        provide = () => {};
+    }
+
+    const baseName = 'mfe-component';
+    const baseUrl = 'http://unpkg.servicetitan.com/mfe';
+    const WEB_COMPONENT_NAME = `${baseName}-abc123`;
+    const metadata = {
+        name: WEB_COMPONENT_NAME,
+        version: `0.0.0-test-abc123`,
+        sharedDependencies: {},
+        dependencies: {},
+        entrypoints: {
+            full: {
+                css: ['full.css'],
+                js: ['full.js'],
+            },
+            light: {
+                css: ['light.css'],
+                js: ['light.js'],
+            },
+            headless: {
+                js: ['headless.js'],
+                css: [],
+            },
+        },
+    };
+    const props = {
+        src: baseUrl,
+        loadingFallback: null,
+    };
+    let onloadRef: Function | null;
+    let getJsonMockFns: Record<string, Function>;
+
+    function initializeGetJsonMockFns() {
+        getJsonMockFns = {
+            [`${props.src}/dist/metadata.json`]: () => {
+                return Promise.resolve({
+                    data: metadata,
+                    headers: {} as Headers,
+                    url: props.src,
+                });
+            },
+        };
+    }
+
+    beforeAll(() => {
+        // register web component in order to test the `provide` method
+        window.customElements.define(`headless-${WEB_COMPONENT_NAME}`, WebComponent);
+
+        /*
+         * mock <script>'s onload so that we can call it directly from the test,
+         * because it won't call itself in the test environment
+         */
+        Object.defineProperty(HTMLScriptElement.prototype, 'onload', {
+            get() {
+                return this._onload;
+            },
+            set(onload: Function) {
+                onloadRef = onload;
+                this._onload = onload;
+            },
+        });
+    });
+
+    beforeEach(() => {
+        jest.resetAllMocks();
+        onloadRef = null;
+        initializeGetJsonMockFns();
+        document.querySelectorAll('script').forEach(script => script.remove());
+        jest.spyOn(common, 'getJson').mockImplementation((url, _) => {
+            if (getJsonMockFns[url] === undefined) {
+                throw new Error(`Unexpected getJson call with url: ${url}`);
+            }
+            return getJsonMockFns[url]();
+        });
+    });
+
+    function subject() {
+        return render(<HeadlessLoader {...props} />);
+    }
+
+    describe('after the script tag added is loaded', () => {
+        async function scriptLoadedSetup() {
+            const result = subject();
+
+            await waitFor(() => onloadRef !== undefined);
+            act(() => {
+                onloadRef!();
+            });
+
+            await waitFor(() => expect(Page.webComponent).toBeInTheDocument());
+
+            return result;
+        }
+
+        test(`adds the headless entrypoint to a script tag`, async () => {
+            await scriptLoadedSetup();
+            const script = document.querySelector('script');
+            expect(script).toHaveAttribute(
+                'src',
+                `${baseUrl}/dist/bundle/headless/${metadata.entrypoints.headless.js[0]}`
+            );
+        });
+
+        test('hides the web component', async () => {
+            await scriptLoadedSetup();
+            expect(Page.webComponent).toHaveStyle('display: none');
+        });
+    });
+});

package/src/__tests__/loader.test.tsx

@@ -15,12 +15,14 @@ import {
 } from '../common';
 import { EVENT_BUS_TOKEN } from '../event-bus';
 import { HistoryManager } from '../history-manager';
-import { Loader, LoaderProps } from '../loader';
+import { Loader, LoaderProps, UnrestrictedLoaderProps } from '../loader';
 import { Metadata } from '../utils/get-bundle-info';
 import { getMFEHasCompatibleLaunchDarklyVersion } from '../utils/get-mfe-has-compatible-launchdarkly-version';
+import { getMFEHasUniqueChunkNamespace } from '../utils/get-mfe-has-unique-chunk-namespace';
 import { getVersionMismatches } from '../utils/get-version-mismatches';
 
 jest.mock('../utils/get-mfe-has-compatible-launchdarkly-version');
+jest.mock('../utils/get-mfe-has-unique-chunk-namespace');
 jest.mock('../utils/get-version-mismatches');
 
 describe('[web-components] Loader', () => {
@@ -121,7 +123,8 @@ describe('[web-components] Loader', () => {
             return getJsonMockFns[url]();
         });
         jest.mocked(getMFEHasCompatibleLaunchDarklyVersion).mockReturnValue(true);
-        jest.mocked(getVersionMismatches).mockReturnValue({});
+        jest.mocked(getVersionMismatches).mockReturnValue(undefined);
+        jest.mocked(getMFEHasUniqueChunkNamespace).mockReturnValue(true);
     });
 
     const Root = () => (
@@ -965,6 +968,12 @@ describe('[web-components] Loader', () => {
         describe('when component was previously loaded', () => {
             beforeEach(() => preloadComponent({ id: 'mfe1' }));
 
+            itNeverReloadsMetadata();
+        });
+
+        describe('when cache is true', () => {
+            beforeEach(() => preloadComponent({ id: 'mfe2', cache: true }));
+
             test('uses cached metadata', () => {
                 subject();
 
@@ -974,22 +983,25 @@ describe('[web-components] Loader', () => {
             itReloadsMetadataAfter(1000 * 60 * 15, 'fifteen minutes');
         });
 
+        describe('when cache is true and mfe does not have unique chunk namespace', () => {
+            beforeEach(() => {
+                jest.mocked(getMFEHasUniqueChunkNamespace).mockReturnValue(false);
+                preloadComponent({ id: 'mfe3', cache: true });
+            });
+
+            itNeverReloadsMetadata();
+        });
+
         describe('when component has custom ttl', () => {
             const customTtl = 1000 * 60; // one minute
 
-            beforeEach(() => preloadComponent({ id: 'mfe2', cache: customTtl }));
+            beforeEach(() => preloadComponent({ id: 'mfe4', cache: customTtl }));
 
             itReloadsMetadataAfter(customTtl, 'custom ttl');
         });
 
-        describe('when component has indefinite ttl', () => {
-            beforeEach(() => preloadComponent({ id: 'mfe3', cache: -1 }));
-
-            itNeverReloadsMetadata();
-        });
-
         describe('when component has zero ttl', () => {
-            beforeEach(() => preloadComponent({ id: 'mfe4', cache: 0 }));
+            beforeEach(() => preloadComponent({ id: 'mfe5', cache: 0 }));
 
             test('always reloads metadata', () => {
                 subject();
@@ -1002,11 +1014,21 @@ describe('[web-components] Loader', () => {
 
         describe("when mfe doesn't have unique chunk namespace", () => {
             beforeEach(() => {
-                preloadComponent({ id: 'mfe5' });
+                preloadComponent({ id: 'mfe6' });
                 setStartupVersion('27.1.1');
             });
 
             itNeverReloadsMetadata();
         });
+
+        describe('when headless mfe is loaded after non-headless mfe', () => {
+            beforeEach(() => {
+                preloadComponent({ id: 'mfe7' });
+                (props as UnrestrictedLoaderProps).isHeadless = true;
+                initializeGetJsonMockFns(props.src);
+            });
+
+            itNeverReloadsMetadata();
+        });
     });
 });

package/src/__tests__/register-headless.test.tsx

@@ -0,0 +1,98 @@
+import '@testing-library/jest-dom';
+import { render, waitFor } from '@testing-library/react';
+
+import { Entries, IWebComponent } from '../common';
+import { HeadlessCallback } from '../register-headless';
+
+export function registerComponent(
+    connectedCallback: HeadlessCallback<unknown>,
+    disconnectedCallback: HeadlessCallback<unknown>,
+    componentName: string | undefined
+) {
+    /*
+     * This register can only happen once, unfortunately. So the connectedCallback and
+     * disconnectedCallback need to work for all tests. If run more than once,
+     * window.customElements.define will throw the error:
+     * "NotSupportedError: This name has already been registered in the registry."
+     *
+     * Also note that there is no way to "unregister" a web component, so an afterAll
+     * cannot be used.
+     */
+    (global as any).WEB_COMPONENT_NAME = componentName;
+    const { registerHeadless } = require('../register-headless');
+    registerHeadless(connectedCallback, disconnectedCallback);
+}
+
+describe('[web-components] registerHeadless', () => {
+    const baseComponentName = 'mock-app';
+    const componentName = `${baseComponentName}-40b38a39`;
+    const connectedCallback = jest.fn().mockName('connectedCallback');
+    const disconnectedCallback = jest.fn().mockName('disconnectedCallback');
+    const provideProps = {
+        ldService: 'ld-service',
+        logService: 'log-service',
+        eventBus: 'event-bus',
+    } as unknown as Entries;
+    const mfeData = { foo: 'bar' };
+    const handleRef = (webComponent: IWebComponent | null) => {
+        webComponent?.provide(provideProps);
+    };
+
+    beforeAll(() => {
+        registerComponent(connectedCallback, disconnectedCallback, componentName);
+    });
+
+    const subject = (props: Record<string, any> = {}, dataAttrs: Record<string, any> = {}) => {
+        jest.spyOn(console, 'error').mockImplementation(jest.fn()); // suppress "attempt to unmount root while rendering" error
+
+        const data = props && { 'data-mfe-data': JSON.stringify(props) };
+        const Component: any = `headless-${componentName}`;
+        const renderResult = render(<Component ref={handleRef} {...data} {...dataAttrs} />);
+
+        return renderResult;
+    };
+
+    beforeEach(() => {
+        jest.clearAllMocks();
+    });
+
+    [connectedCallback, disconnectedCallback].forEach(callback => {
+        test(`calls ${callback.getMockName()} with mfeData`, async () => {
+            const renderResult = subject({}, { 'data-mfe-data': JSON.stringify(mfeData) });
+            renderResult.unmount();
+
+            await waitFor(() => {
+                expect(callback).toHaveBeenCalledWith(
+                    expect.objectContaining({
+                        mfeData,
+                    })
+                );
+            });
+        });
+    });
+
+    [connectedCallback, disconnectedCallback].forEach(callback => {
+        (['ldService', 'logService', 'eventBus'] as const).forEach(service => {
+            test(`calls ${callback.getMockName()} with ${service}`, async () => {
+                const renderResult = subject();
+                renderResult.unmount();
+
+                await waitFor(() => {
+                    expect(callback).toHaveBeenCalledWith(
+                        expect.objectContaining({
+                            [service]: provideProps[service],
+                        })
+                    );
+                });
+            });
+        });
+    });
+
+    test('logs an error when WEB_COMPONENT_NAME is not set', () => {
+        const consoleSpy = jest.spyOn(console, 'error').mockImplementation(jest.fn());
+        jest.isolateModules(() => {
+            registerComponent(connectedCallback, disconnectedCallback, undefined);
+        });
+        expect(consoleSpy).toHaveBeenCalledWith('"WEB_COMPONENT_NAME" is not defined!');
+    });
+});

package/src/headless-loader.tsx

@@ -0,0 +1,21 @@
+import { UnrestrictedLoaderProps, Loader } from './loader';
+
+type HeadlessLoaderProps<T> = Pick<
+    UnrestrictedLoaderProps<T>,
+    'src' | 'fallbackSrc' | 'data' | 'className' | 'retries' | 'cache' | 'onRequestError'
+>;
+
+const UnrestrictedPropsLoader = <T,>(props: UnrestrictedLoaderProps<T>) => {
+    return <Loader {...props} />;
+};
+
+export function HeadlessLoader<T>(props: Readonly<HeadlessLoaderProps<T>>) {
+    return (
+        <UnrestrictedPropsLoader<T>
+            {...props}
+            isHeadless
+            loadingFallback={null}
+            errorFallback={null}
+        />
+    );
+}

package/src/index.ts

@@ -2,8 +2,10 @@ export * from './common';
 export * from './contexts';
 export * from './event-bus';
 export * from './get-value-for-environment';
+export * from './headless-loader';
 export * from './history-manager';
 export * from './loader';
 export * from './register';
+export * from './register-headless';
 
 export type { JSON, JSONPrimitive, Serializable } from './types';

package/src/loader.tsx

@@ -1,6 +1,7 @@
 import {
     ReactElement,
     ReactNode,
+    Ref,
     Suspense,
     forwardRef,
     lazy,
@@ -28,7 +29,6 @@ import { EventBus, EVENT_BUS_TOKEN } from './event-bus';
 import { EXPOSED_DEPENDENCIES, EXPOSED_INSTANCE_DEPENDENCIES } from './globals';
 import {
     BundleInfo,
-    TtlCache,
     getBundleInfo,
     getLDServiceToken,
     validateBundleInfo,
@@ -40,7 +40,7 @@ export type LoaderRef = EventBus;
 
 export type FallbackNode = NonNullable<ReactNode> | null;
 
-export interface LoaderProps<T> {
+export interface UnrestrictedLoaderProps<T = {}> {
     src: string;
     fallbackSrc?: string;
     /** Values in the object will be stringified and then parsed before being delivered to the MFE via props or context. */
@@ -51,16 +51,32 @@ export interface LoaderProps<T> {
     errorFallback?: FallbackNode;
     className?: string;
     retries?: number;
+    isHeadless?: boolean;
     cache?: boolean | number;
     onRequestError?(error: GetJsonError): boolean;
 }
 
-export type LoaderDataProps = Pick<LoaderProps<{}>, 'data' | 'className'> & {
+export type LoaderProps<T> = Pick<
+    UnrestrictedLoaderProps<T>,
+    | 'src'
+    | 'fallbackSrc'
+    | 'data'
+    | 'basename'
+    | 'loadingFallback'
+    | 'loadingFallbackDelayed'
+    | 'errorFallback'
+    | 'className'
+    | 'retries'
+    | 'cache'
+    | 'onRequestError'
+>;
+
+export type LoaderDataProps = Pick<UnrestrictedLoaderProps, 'data' | 'className'> & {
     LoadingFallback: () => JSX.Element;
 };
 
-export const Loader = forwardRef<LoaderRef, LoaderProps<{}>>((props, ref) => {
-    const { cache = true, basename, fallbackSrc, onRequestError, retries, src } = props;
+const UnrestrictedLoader = <T,>(props: UnrestrictedLoaderProps<T>, ref: Ref<LoaderRef>) => {
+    const { cache = -1, basename, fallbackSrc, isHeadless, onRequestError, retries, src } = props;
     const { loadingFallback, loadingFallbackDelayed = true } = props;
 
     const bus = useEventBus();
@@ -97,6 +113,7 @@ export const Loader = forwardRef<LoaderRef, LoaderProps<{}>>((props, ref) => {
                 exposedInstanceDependencies,
                 eventBus,
                 fallbackSrc,
+                isHeadless,
                 logService,
                 onRequestError,
                 retries,
@@ -109,9 +126,10 @@ export const Loader = forwardRef<LoaderRef, LoaderProps<{}>>((props, ref) => {
             exposedDependencies,
             exposedInstanceDependencies,
             eventBus,
+            fallbackSrc,
+            isHeadless,
             logService,
             onRequestError,
-            fallbackSrc,
             retries,
             src,
         ]
@@ -130,14 +148,19 @@ export const Loader = forwardRef<LoaderRef, LoaderProps<{}>>((props, ref) => {
             </Suspense>
         </ErrorBoundary>
     );
-});
+};
 
-type LazyLoaderProps = LoaderProps<any> & {
+export const Loader = forwardRef(UnrestrictedLoader) as <T = {}>(
+    props: LoaderProps<NoInfer<T>> & { ref?: Ref<LoaderRef> }
+) => ReturnType<typeof UnrestrictedLoader>;
+
+type LazyLoaderProps = UnrestrictedLoaderProps<any> & {
     cancelation: AbortController;
     exposedDependencies?: ExposedDependencies;
     exposedInstanceDependencies?: ExposedInstanceDependencies;
     eventBus: EventBus;
     logService?: Log;
+    cache: Required<UnrestrictedLoaderProps<any>>['cache'];
 };
 
 function lazyLoader(props: LazyLoaderProps) {
@@ -165,58 +188,50 @@ function lazyLoader(props: LazyLoaderProps) {
 function lazyWebComponent(props: LazyLoaderProps) {
     const {
         basename,
+        cache,
         cancelation,
         exposedDependencies,
         exposedInstanceDependencies,
         eventBus,
         fallbackSrc,
+        isHeadless,
         logService,
         onRequestError,
         retries,
         src,
     } = props;
 
-    let { cache } = props;
-
     return lazy<(_: LoaderDataProps) => JSX.Element | null>(async () => {
-        let bundleInfo: BundleInfo | undefined = cache ? bundleCache.get(src) : undefined;
-        if (!bundleInfo) {
-            try {
-                bundleInfo = await getBundleInfo({
-                    mainPackageUrl: src,
-                    fallbackPackageUrl: fallbackSrc,
-                    exposedDependencies,
-                    exposedInstanceDependencies,
-                    signal: cancelation.signal,
-                    retries,
-                    onRequestError,
-                });
-            } catch (e) {
-                if (cancelation.signal.aborted) {
-                    return {
-                        default: () => null,
-                    };
-                }
-
-                throw e;
-            }
-
-            if (cache === true && !bundleInfo.mfeHasUniqueChunkNamespace) {
-                cache = -1;
-            }
-
-            if (cache) {
-                bundleCache.set(src, bundleInfo, typeof cache === 'number' ? cache : undefined);
-            }
-
-            validateBundleInfo(bundleInfo, {
+        let bundleInfo: BundleInfo;
+        try {
+            bundleInfo = await getBundleInfo({
+                cache,
+                mainPackageUrl: src,
+                fallbackPackageUrl: fallbackSrc,
+                isHeadless,
                 exposedDependencies,
                 exposedInstanceDependencies,
-                logService,
-                packageUrl: src,
+                signal: cancelation.signal,
+                retries,
+                onRequestError,
             });
+        } catch (e) {
+            if (cancelation.signal.aborted) {
+                return {
+                    default: () => null,
+                };
+            }
+
+            throw e;
         }
 
+        validateBundleInfo(bundleInfo, {
+            exposedDependencies,
+            exposedInstanceDependencies,
+            logService,
+            packageUrl: src,
+        });
+
         await loadScripts(bundleInfo);
 
         const ldService = bundleInfo.mfeHasCompatibleLaunchDarklyVersion
@@ -264,6 +279,3 @@ function ensureLDService(
 function useEventBus() {
     return useRef(new EventBus()).current;
 }
-
-const MINUTE = 1000 * 60;
-const bundleCache = new TtlCache<BundleInfo>({ ttlMs: 15 * MINUTE });

package/src/register-headless.ts

@@ -0,0 +1,81 @@
+import type { LDService } from '@servicetitan/launchdarkly-service';
+import type { Entries, IWebComponent } from './common';
+import type { EventBus } from './event-bus';
+import type { Log } from '@servicetitan/log-service';
+import { Serializable } from './types';
+
+type HeadlessCallbackArgs<T> = Pick<Entries, 'ldService' | 'logService' | 'eventBus'> & {
+    mfeData?: Serializable<T>;
+};
+export type HeadlessCallback<T = undefined> = (params: HeadlessCallbackArgs<T>) => void;
+
+export function registerHeadless(
+    connectedCallback?: HeadlessCallback<unknown>,
+    disconnectedCallback?: HeadlessCallback<unknown>
+) {
+    class Headless extends HTMLElement implements IWebComponent {
+        private ldService?: LDService;
+        private logService?: Log;
+        private eventBus?: EventBus;
+        private readonly readyPromise: Promise<void>;
+        private resolveReadyPromise!: () => void;
+
+        constructor() {
+            super();
+            this.readyPromise = new Promise(resolve => {
+                this.resolveReadyPromise = resolve;
+            });
+        }
+
+        provide = (entries: Entries) => {
+            this.ldService = entries.ldService;
+            this.logService = entries.logService;
+            this.eventBus = entries.eventBus;
+            this.resolveReadyPromise();
+        };
+
+        async connectedCallback() {
+            await this.readyPromise;
+            connectedCallback?.({
+                ...this.services,
+                mfeData: this.mfeData,
+            });
+        }
+
+        async disconnectedCallback() {
+            await this.readyPromise;
+            disconnectedCallback?.({
+                ...this.services,
+                mfeData: this.mfeData,
+            });
+        }
+
+        connectedMoveCallback() {
+            /*
+             * Defining connectedMoveCallback prevents connectedCallback or disconnectedCallback
+             * from running when the element is moved in the DOM
+             * https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#custom_element_lifecycle_callbacks
+             */
+        }
+
+        private get services() {
+            return {
+                ldService: this.ldService,
+                logService: this.logService,
+                eventBus: this.eventBus,
+            };
+        }
+
+        private get mfeData() {
+            return JSON.parse(this.dataset.mfeData ?? '{}');
+        }
+    }
+
+    if (!WEB_COMPONENT_NAME) {
+        // eslint-disable-next-line no-console
+        console.error('"WEB_COMPONENT_NAME" is not defined!');
+        return;
+    }
+
+    window.customElements.define(`headless-${WEB_COMPONENT_NAME}`, Headless);
+}

package/src/types.ts

@@ -11,3 +11,12 @@ export type Serializable<T> = {
             ? Serializable<U>[]
             : Serializable<T[P]>;
 };
+
+export interface Metadata {
+    name: string;
+    version?: string;
+    bundledWith?: Record<string, string | undefined>;
+    sharedDependencies: Record<string, string>;
+    dependencies?: Record<string, string>;
+    entrypoints?: Record<string, { css: string[]; js: string[] }>;
+}

package/src/utils/__tests__/get-version-mismatches.test.ts

@@ -27,7 +27,7 @@ describe(`[web-components] ${getVersionMismatches.name}`, () => {
         test('returns no mismatches', () => {
             expect(
                 getVersionMismatches(exposedDependencies, dependencies, sharedDependencies)
-            ).toEqual({});
+            ).toEqual(undefined);
         });
     }