[ARGG-876] Add support for withScrimmedPortal with SSR

packages/bpk-scrim-utils/README.md

@@ -21,6 +21,8 @@ const BoxWithScrim = withScrim(Box);
 
 The version using a [React portal](https://react.dev/reference/react-dom/createPortal) renders the wrapped component in a different part of the DOM. It also provides an `isPortalReady` prop to notify when the component inside the portal is ready to be used. This may be necessary to interact with the content of the component in a `useEffect` hook, for example to set the focus on mount.
 
+The `withScrimmedPortal` runs by default only on client due to the use of the portal. However, it accepts the `runOnSSR` prop which, when passed, renders a scrim on the server to block users from interacting with the page and making it evident that the page is not interactive.
+
 ```js
 import { withScrimmedPortal } from '@skyscanner/backpack-web/bpk-scrim-utils';
 

packages/bpk-scrim-utils/src/withScrimmedPortal-test.tsx

@@ -17,35 +17,36 @@
  */
 
 import '@testing-library/jest-dom';
-import { render, within, screen } from '@testing-library/react';
+import { render, within, screen, isInaccessible } from '@testing-library/react';
 import { useEffect, useState } from 'react';
+import { renderToString } from 'react-dom/server';
 
 import withScrimmedPortal from './withScrimmedPortal';
 import type { Props } from './withScrimmedPortal';
 
 describe('withScrimmedPortal', () => {
   it('renders the wrapped component inside a portal correctly with fallback to document.body', () => {
-    const DialogContent = () => <div>Dialog content</div>;
+    const DialogContent = () => <div data-testid="dialog-content">Dialog content</div>;
     const ScrimmedComponent = withScrimmedPortal(DialogContent);
 
     render(
       <div id="pagewrap">
-        <div> Content hidden from AT</div>
+        <div data-testid="hidden"> Content hidden from AT</div>
         <ScrimmedComponent
           getApplicationElement={() => document.getElementById('pagewrap')}
         />
       </div>
     );
-    expect(document.body).toMatchSnapshot();
+    expect(document.body).toContainElement(screen.getByTestId('dialog-content'));
   });
 
   it('renders the wrapped component inside a portal with renderTarget provided', () => {
-    const WrappedComponent = () => <div>Wrapped Component</div>;
-    const ScrimmedComponent = withScrimmedPortal(WrappedComponent);
+    const DialogContent = () => <div data-testid="dialog-content">Dialog content</div>;
+    const ScrimmedComponent = withScrimmedPortal(DialogContent);
       render(
         <div>
           <div id="pagewrap">
-            <div> Content hidden from AT</div>
+            <div data-testid="hidden"> Content hidden from AT</div>
             <ScrimmedComponent
               getApplicationElement={() => document.getElementById('pagewrap')}
               renderTarget={() => document.getElementById('modal-container')}
@@ -54,11 +55,13 @@ describe('withScrimmedPortal', () => {
           <div id="modal-container" />
        </div>
       );
-      expect(document.body).toMatchSnapshot();
+      expect(
+        document.getElementById('modal-container')
+      ).toContainElement(screen.getByTestId('dialog-content'));
   });
 
   it('renders the wrapped component outside the applicationElement', () => {
-    const WrappedComponent = () => <div>Wrapped Component</div>;
+    const WrappedComponent = () => <div data-testid="dialog-content">Wrapped Component</div>;
     const ScrimmedComponent = withScrimmedPortal(WrappedComponent);
     render(
       <div>
@@ -105,4 +108,51 @@ describe('withScrimmedPortal', () => {
 
     expect(screen.getByText('Wrapped Component / portal is not ready yet / portal is now ready')).toBeInTheDocument();
   });
+
+  it('renders the wrapped component inside a portal correctly when runOnServer is false (default)', () => {
+    const DialogContent = () => <div data-testid="dialog-content">Dialog content</div>;
+    const ScrimmedComponent = withScrimmedPortal(DialogContent);
+
+    render(
+      <div id="pagewrap">
+        <div> Content hidden from AT</div>
+        <ScrimmedComponent
+          getApplicationElement={() => document.getElementById('pagewrap')}
+          runOnServer={false}
+        />
+      </div>
+    );
+    expect(document.body).toContainElement(screen.getByTestId('dialog-content'));
+  });
+
+  it('renders the wrapped component inside a portal correctly when runOnServer is true', () => {
+    const DialogContent = () => <div data-testid="dialog-content">Dialog content</div>;
+    const ScrimmedComponent = withScrimmedPortal(DialogContent);
+
+    render(
+      <div id="pagewrap">
+        <div> Content hidden from AT</div>
+        <ScrimmedComponent
+          getApplicationElement={() => document.getElementById('pagewrap')}
+          runOnServer
+        />
+      </div>
+    );
+    expect(document.body).toContainElement(screen.getByTestId('dialog-content'));
+  });
+
+  it('throws an error when runOnServer is false and component is rendered on the server', () => {
+    const DialogContent = () => <div>Dialog content</div>;
+    const ScrimmedComponent = withScrimmedPortal(DialogContent);
+
+    expect(() => renderToString(
+      <div id="pagewrap">
+        <div> Content hidden from AT</div>
+        <ScrimmedComponent
+          getApplicationElement={() => document.getElementById('pagewrap')}
+          runOnServer={false}
+        />
+      </div>
+    )).toThrow();
+  });
 });

packages/bpk-scrim-utils/src/withScrimmedPortal.tsx

@@ -21,10 +21,15 @@ import { useState, useEffect } from 'react';
 import { createPortal } from 'react-dom';
 
 import withScrim from './withScrim';
+import BpkScrim from './BpkScrim';
 import type { Props as ScrimProps } from './withScrim';
 
 export type Props = ScrimProps & {
     renderTarget?: (() => HTMLElement | null) | null;
+    /**
+     * If true, the component will run on both server and client.
+     */
+    runOnServer?: boolean;
 };
 
 const getPortalElement = (target: (() => HTMLElement | null) | null | undefined) => {
@@ -37,22 +42,34 @@ const getPortalElement = (target: (() => HTMLElement | null) | null | undefined)
     if (document.body) {
         return document.body;
     }
-    throw new Error('Render target and fallback unavailable');
+    throw new Error('Render target and fallback unavailable. The ScrimmedComponent uses a portal making it unsuitable for SSR. If you are trying to render on SSR, please pass the `runOnServer` prop.');
 }
 
 const withScrimmedPortal = (WrappedComponent: ComponentType<ScrimProps>) => {
     const Scrimmed = withScrim(WrappedComponent);
 
-    const ScrimmedComponent = ({ renderTarget, ...rest}: Props) => {
-        const portalElement = getPortalElement(renderTarget);
-
+    const ScrimmedComponent = ({ renderTarget, runOnServer = false, ...rest}: Props) => {
         const [isPortalReady, setIsPortalReady] = useState(false);
 
         useEffect(() => {
             setIsPortalReady(true);
           }, []);
 
-        return createPortal(<Scrimmed {...rest} isPortalReady={isPortalReady} />, portalElement);
+        /**
+         * The following code runs only on the client.
+         * If consumer passes runOnServer as false (meaning they want to render the component on client only), we render the component as normal.
+         * If consumer passes runOnServer as true (meaning they want to render the component on server and client), we render the component as normal once the component has been mounted.
+         * This is to ensure the snapshotted markup (initial render before the component has been mounted) is the same on both server and client.
+         */
+        if (!runOnServer || isPortalReady) {
+            const portalElement = getPortalElement(renderTarget);
+            return createPortal(<Scrimmed {...rest} isPortalReady={isPortalReady} />, portalElement);
+        }
+
+        /**
+         * The following code will run on both server and on the intial render on the client when consumers opts for both SSR and CSR i.e. by passing the `runOnServer` prop.
+         */
+        return <BpkScrim />;
     }
 
     return ScrimmedComponent;