refactor(ui): live preview iframe loader (#16004)

Continuation of #15999.

Without optimistically loading the live preview window, the initial
loading state is left unhandled when toggling into live preview for the
first time. This causes users to see blank content until the iframe has
loaded, without indication that something is happening.

Now, we display a loading indicator while the iframe request is in
flight, that notably:
1. Only shows if the load takes longer than x ms.
2. If shown, is forced to remain in place for _at least_ x ms to avoid
flickering, even if the request finishes before then.

Before:


https://github.com/user-attachments/assets/70852e80-ac0e-4b96-b59e-8817c65629a6

After:


https://github.com/user-attachments/assets/5fda30d9-8c87-42bc-ba20-a8f7ae8f1245

Related:
- The `ShimmerEffect` component now accepts arbitrary HTML attributes
and supports a new `transparent` prop

---
- To see the specific tasks where the Asana app for GitHub is being
used, see below:
  - https://app.asana.com/0/0/1213727956884086

Author: jacobsfletch

packages/ui/src/elements/IframeLoader/index.scss

@@ -0,0 +1,21 @@
+@layer payload-default {
+  .iframe-loader__container {
+    width: 100%;
+    height: 100%;
+    position: relative;
+    flex: 1;
+    min-height: 0;
+  }
+
+  .iframe-loader__iframe {
+    background-color: white;
+    border: 0;
+    width: 100%;
+    height: 100%;
+    transform-origin: top left;
+  }
+
+  .iframe-loader__iframe--is-loading {
+    opacity: 0;
+  }
+}

packages/ui/src/elements/IframeLoader/index.tsx

@@ -0,0 +1,128 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+import { ShimmerEffect } from '../ShimmerEffect/index.js'
+import './index.scss'
+
+export type IframeLoaderProps = {
+  ref?: React.Ref<HTMLIFrameElement>
+} & React.IframeHTMLAttributes<HTMLIFrameElement>
+
+const shimmerDelays = {
+  minVisible: 300,
+  show: 1000,
+}
+
+const baseClass = 'iframe-loader'
+
+/**
+ * Loads an `iframe` element with the given source behind a loading indicator.
+ * Notable behaviors:
+ * 1. Only show if the load takes longer than x ms.
+ * 2. Once shown, force it to be visible for at least x ms to avoid flickering, even if the iframe loads before then.
+ */
+export const IframeLoader: React.FC<IframeLoaderProps> = ({
+  onLoad: onLoadFromProps,
+  src,
+  title,
+  ...rest
+}) => {
+  const [isLoading, setIsLoading] = useState(Boolean(src))
+  const [showShimmer, setShowShimmer] = useState(false)
+  const shimmerShownAtRef = useRef(0)
+
+  const showTimerRef = useRef<null | ReturnType<typeof setTimeout>>(null)
+
+  const hideTimerRef = useRef<null | ReturnType<typeof setTimeout>>(null)
+
+  const clearTimers = useCallback(() => {
+    if (showTimerRef.current) {
+      clearTimeout(showTimerRef.current)
+      showTimerRef.current = null
+    }
+
+    if (hideTimerRef.current) {
+      clearTimeout(hideTimerRef.current)
+      hideTimerRef.current = null
+    }
+  }, [])
+
+  useEffect(() => {
+    clearTimers()
+    setIsLoading(Boolean(src))
+    setShowShimmer(false)
+    shimmerShownAtRef.current = 0
+
+    if (!src) {
+      return
+    }
+
+    showTimerRef.current = setTimeout(() => {
+      setShowShimmer(true)
+      shimmerShownAtRef.current = Date.now()
+      showTimerRef.current = null
+    }, shimmerDelays.show)
+
+    return () => {
+      if (showTimerRef.current) {
+        clearTimeout(showTimerRef.current)
+        showTimerRef.current = null
+      }
+    }
+  }, [clearTimers, src])
+
+  useEffect(() => {
+    return () => {
+      clearTimers()
+    }
+  }, [clearTimers])
+
+  const onLoad = useCallback<React.IframeHTMLAttributes<HTMLIFrameElement>['onLoad']>(
+    (e) => {
+      if (typeof onLoadFromProps === 'function') {
+        onLoadFromProps(e)
+      }
+
+      setIsLoading(false)
+
+      if (showTimerRef.current) {
+        clearTimeout(showTimerRef.current)
+        showTimerRef.current = null
+      }
+
+      if (!showShimmer) {
+        return
+      }
+
+      const elapsed = Date.now() - shimmerShownAtRef.current
+      const remainingVisible = Math.max(0, shimmerDelays.minVisible - elapsed)
+
+      if (remainingVisible === 0) {
+        setShowShimmer(false)
+        return
+      }
+
+      hideTimerRef.current = setTimeout(() => {
+        setShowShimmer(false)
+        hideTimerRef.current = null
+      }, remainingVisible)
+    },
+    [showShimmer, onLoadFromProps],
+  )
+
+  return (
+    <div className={`${baseClass}__container`}>
+      {showShimmer && <ShimmerEffect aria-live="polite" height="100%" role="status" transparent />}
+      <iframe
+        {...rest}
+        className={[`${baseClass}__iframe`, isLoading && `${baseClass}__iframe--is-loading`]
+          .filter(Boolean)
+          .join(' ')}
+        onLoad={onLoad}
+        // eslint-disable-next-line
+        sandbox="allow-same-origin allow-scripts allow-forms allow-popups allow-modals allow-downloads"
+        src={src}
+        title={title}
+      />
+    </div>
+  )
+}

packages/ui/src/elements/LivePreview/IFrame/index.scss

@@ -10,9 +10,8 @@ import { useDocumentEvents } from '../../../providers/DocumentEvents/index.js'
 import { useDocumentInfo } from '../../../providers/DocumentInfo/index.js'
 import { useLivePreviewContext } from '../../../providers/LivePreview/context.js'
 import { useLocale } from '../../../providers/Locale/index.js'
-import { ShimmerEffect } from '../../ShimmerEffect/index.js'
+import { IframeLoader } from '../../IframeLoader/index.js'
 import { DeviceContainer } from '../Device/index.js'
-import { IFrame } from '../IFrame/index.js'
 import { LivePreviewToolbar } from '../Toolbar/index.js'
 import './index.scss'
 
@@ -27,8 +26,10 @@ export const LivePreviewWindow: React.FC<EditViewProps> = (props) => {
     loadedURL,
     popupRef,
     previewWindowType,
+    setLoadedURL,
     shouldRenderIframe,
     url,
+    zoom,
   } = useLivePreviewContext()
 
   const locale = useLocale()
@@ -135,7 +136,20 @@ export const LivePreviewWindow: React.FC<EditViewProps> = (props) => {
         <LivePreviewToolbar {...props} />
         <div className={`${baseClass}__main`}>
           <DeviceContainer>
-            {url && shouldRenderIframe ? <IFrame /> : <ShimmerEffect height="100%" />}
+            {shouldRenderIframe && (
+              <IframeLoader
+                className="live-preview-iframe"
+                id="live-preview-iframe"
+                onLoad={() => {
+                  setLoadedURL(url)
+                }}
+                ref={iframeRef}
+                src={url}
+                style={{
+                  transform: typeof zoom === 'number' ? `scale(${zoom}) ` : undefined,
+                }}
+              />
+            )}
           </DeviceContainer>
         </div>
       </div>

packages/ui/src/elements/LivePreview/IFrame/index.tsx

@@ -1,8 +1,11 @@
 @layer payload-default {
   .shimmer-effect {
+    --shine-bg: var(--theme-elevation-50);
+    --shine-fg: var(--theme-elevation-150);
+
     position: relative;
     overflow: hidden;
-    background-color: var(--theme-elevation-50);
+    background-color: var(--shine-bg);
 
     &__shine {
       position: absolute;
@@ -14,13 +17,18 @@
       opacity: 0.75;
       background: linear-gradient(
         100deg,
-        var(--theme-elevation-50) 0%,
-        var(--theme-elevation-50) 15%,
-        var(--theme-elevation-150) 50%,
-        var(--theme-elevation-50) 85%,
-        var(--theme-elevation-50) 100%
+        var(--shine-bg) 0%,
+        var(--shine-bg) 15%,
+        var(--shine-fg) 50%,
+        var(--shine-bg) 85%,
+        var(--shine-bg) 100%
       );
     }
+
+    &--transparent {
+      --shine-bg: transparent;
+      --shine-fg: var(--theme-elevation-100);
+    }
   }
 
   @keyframes shimmer {

packages/ui/src/elements/LivePreview/Window/index.tsx

@@ -9,20 +9,32 @@ export type ShimmerEffectProps = {
   readonly className?: string
   readonly disableInlineStyles?: boolean
   readonly height?: number | string
+  /**
+   * When true, adjusts the gradient to allow the natural background of the element to shine through.
+   */
+  transparent?: boolean
   readonly width?: number | string
-}
+} & React.HTMLAttributes<HTMLDivElement>
+
+const baseClass = 'shimmer-effect'
 
 export const ShimmerEffect: React.FC<ShimmerEffectProps> = ({
   animationDelay = '0ms',
   className,
   disableInlineStyles = false,
   height = '60px',
+  transparent,
   width = '100%',
+  ...rest
 }) => {
   return (
     <div
-      className={['shimmer-effect', className].filter(Boolean).join(' ')}
+      {...rest}
+      className={[baseClass, transparent && `${baseClass}--transparent`, className]
+        .filter(Boolean)
+        .join(' ')}
       style={{
+        ...(rest?.style || {}),
         height: !disableInlineStyles && (typeof height === 'number' ? `${height}px` : height),
         width: !disableInlineStyles && (typeof width === 'number' ? `${width}px` : width),
       }}

packages/ui/src/elements/ShimmerEffect/index.scss

@@ -1,7 +1,42 @@
-import type { Page, Route } from '@playwright/test'
+import type { FrameLocator, Page, Route } from '@playwright/test'
 
 import { expect } from '@playwright/test'
 
+/**
+ * Match this to whatever the component uses.
+ */
+const livePreviewIframeID = 'live-preview-iframe'
+
+export const getLivePreviewIframe = async (
+  page: Page,
+  options?: {
+    expectIframeSrcToMatch?: RegExp
+  },
+): Promise<{
+  frame: FrameLocator
+  iframe: ReturnType<Page['locator']>
+}> => {
+  const { expectIframeSrcToMatch } = options || {}
+
+  const iframe = page.locator(`#${livePreviewIframeID}`)
+
+  if (expectIframeSrcToMatch) {
+    await expect.poll(async () => iframe.getAttribute('src')).toMatch(expectIframeSrcToMatch)
+  }
+
+  const frame = getLivePreviewIframeFrame(page)
+
+  return {
+    iframe,
+    frame,
+  }
+}
+
+export const getLivePreviewIframeFrame = (page: Page): FrameLocator => {
+  const frame = page.frameLocator(`#${livePreviewIframeID}`)
+  return frame
+}
+
 const endpoint = '**/api/payload-preferences/**'
 
 export const toggleLivePreview = async (
@@ -38,14 +73,16 @@ export const toggleLivePreview = async (
       await toggler.click()
       hasClickedToggler = true
       await expect(toggler).not.toHaveClass(/live-preview-toggler--active/)
-      await expect(page.locator('iframe.live-preview-iframe')).toBeHidden()
+      const { iframe } = await getLivePreviewIframe(page)
+      await expect(iframe).toBeHidden()
     }
 
     if (!isActive && (options?.targetState === 'on' || !options?.targetState)) {
       await toggler.click()
       hasClickedToggler = true
       await expect(toggler).toHaveClass(/live-preview-toggler--active/)
-      await expect(page.locator('iframe.live-preview-iframe')).toBeVisible()
+      const { iframe } = await getLivePreviewIframe(page)
+      await expect(iframe).toBeVisible()
     }
 
     if (hasClickedToggler) {