fix: Render Visual Refresh background height in sync with content

pages/app-layout/full-page-table-with-variable-header-height.page.tsx

@@ -0,0 +1,38 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import React from 'react';
+import AppLayout from '~components/app-layout';
+import labels from './utils/labels';
+import Table from '~components/table';
+import { generateItems, Instance } from '../table/generate-data';
+import { columnsConfig } from '../table/shared-configs';
+import ExpandableSection from '~components/expandable-section';
+import Header from '~components/header';
+
+const items = generateItems(20);
+
+export default function () {
+  return (
+    <AppLayout
+      ariaLabels={labels}
+      contentType="table"
+      navigationHide={true}
+      content={
+        <Table<Instance>
+          header={
+            <>
+              <Header variant="awsui-h1-sticky">Header that changes size when scrolling</Header>
+              <ExpandableSection headerText="Click to expand header area">
+                <div style={{ height: '300px' }}>Content</div>
+              </ExpandableSection>
+            </>
+          }
+          stickyHeader={true}
+          variant="full-page"
+          columnDefinitions={columnsConfig}
+          items={items}
+        />
+      }
+    />
+  );
+}

src/app-layout/__tests__/dynamic-overlap.test.tsx

@@ -0,0 +1,106 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+import AppLayout, { AppLayoutProps } from '../../../lib/components/app-layout';
+import { useDynamicOverlap } from '../../../lib/components/internal/hooks/use-dynamic-overlap';
+import { useAppLayoutInternals } from '../../../lib/components/app-layout/visual-refresh/context';
+
+jest.mock('../../../lib/components/internal/hooks/use-visual-mode', () => ({
+  ...jest.requireActual('../../../lib/components/internal/hooks/use-visual-mode'),
+  useVisualRefresh: jest.fn().mockReturnValue(true),
+}));
+
+let positiveHeight = true;
+
+jest.mock('../../../lib/components/internal/hooks/container-queries/utils', () => ({
+  ...jest.requireActual('../../../lib/components/internal/hooks/container-queries/utils'),
+  convertResizeObserverEntry: () => ({ contentBoxHeight: positiveHeight ? 800 : 0 }),
+}));
+
+describe('Dynamic overlap', () => {
+  function ComponentWithDynamicOverlap() {
+    const ref = useDynamicOverlap();
+    const { isDynamicOverlapSet, isDynamicOverlapDisabled } = useAppLayoutInternals();
+    return (
+      <>
+        <div ref={ref} />
+        <div data-testid="is-dynamic-overlap-set">{isDynamicOverlapSet.toString()}</div>
+        <div data-testid="is-dynamic-overlap-disabled">{isDynamicOverlapDisabled.toString()}</div>
+      </>
+    );
+  }
+
+  function ComponentWithoutDynamicOverlap() {
+    const { isDynamicOverlapSet, isDynamicOverlapDisabled } = useAppLayoutInternals();
+    return (
+      <>
+        <div data-testid="is-dynamic-overlap-set">{isDynamicOverlapSet.toString()}</div>
+        <div data-testid="is-dynamic-overlap-disabled">{isDynamicOverlapDisabled.toString()}</div>
+      </>
+    );
+  }
+
+  function renderApp(appLayoutProps?: AppLayoutProps) {
+    const { rerender } = render(<AppLayout {...appLayoutProps} />);
+    return {
+      isDynamicOverlapSet: () => screen.getByTestId('is-dynamic-overlap-set').textContent,
+      isDynamicOverlapDisabled: () => screen.getByTestId('is-dynamic-overlap-disabled').textContent,
+      rerender: (appLayoutProps?: AppLayoutProps) => rerender(<AppLayout {...appLayoutProps} />),
+    };
+  }
+
+  beforeEach(() => {
+    positiveHeight = true;
+  });
+
+  test('sets dynamic overlap when content header is present', () => {
+    const { isDynamicOverlapSet, isDynamicOverlapDisabled } = renderApp({
+      content: <ComponentWithDynamicOverlap />,
+      contentHeader: 'Content header',
+    });
+    expect(isDynamicOverlapSet()).toBe('true');
+    expect(isDynamicOverlapDisabled()).toBe('false');
+  });
+
+  test('sets dynamic overlap when height is higher than 0', () => {
+    const { isDynamicOverlapSet, isDynamicOverlapDisabled } = renderApp({ content: <ComponentWithDynamicOverlap /> });
+    expect(isDynamicOverlapSet()).toBe('true');
+    expect(isDynamicOverlapDisabled()).toBe('false');
+  });
+
+  test('does not set dynamic overlap when no content header is present and height is 0', () => {
+    positiveHeight = false;
+    const { isDynamicOverlapSet, isDynamicOverlapDisabled } = renderApp({ content: <ComponentWithDynamicOverlap /> });
+    expect(isDynamicOverlapSet()).toBe('false');
+    expect(isDynamicOverlapDisabled()).toBe('true');
+  });
+
+  test('does not set dynamic overlap when the useDynamicOverlap hook is not used', () => {
+    const { isDynamicOverlapSet, isDynamicOverlapDisabled } = renderApp({
+      content: <ComponentWithoutDynamicOverlap />,
+      disableContentHeaderOverlap: true,
+    });
+    expect(isDynamicOverlapSet()).toBe('false');
+    expect(isDynamicOverlapDisabled()).toBe('true');
+  });
+
+  test('disables dynamic overlap when explicitly specified in the app layout props', () => {
+    const { isDynamicOverlapDisabled } = renderApp({
+      content: <ComponentWithDynamicOverlap />,
+      disableContentHeaderOverlap: true,
+    });
+    expect(isDynamicOverlapDisabled()).toBe('true');
+  });
+
+  test('updates state accordingly when re-rendering', () => {
+    const { isDynamicOverlapSet, isDynamicOverlapDisabled, rerender } = renderApp({
+      content: <ComponentWithDynamicOverlap />,
+    });
+    expect(isDynamicOverlapSet()).toBe('true');
+    expect(isDynamicOverlapDisabled()).toBe('false');
+    rerender({ content: <ComponentWithoutDynamicOverlap /> });
+    expect(isDynamicOverlapSet()).toBe('false');
+    expect(isDynamicOverlapDisabled()).toBe('true');
+  });
+});

src/app-layout/visual-refresh/background.tsx

@@ -8,15 +8,14 @@ import styles from './styles.css.js';
 export default function Background() {
   const {
     breadcrumbs,
-    contentHeader,
-    dynamicOverlapHeight,
+    isDynamicOverlapSet,
     hasNotificationsContent,
     hasStickyBackground,
     isMobile,
     stickyNotifications,
   } = useAppLayoutInternals();
 
-  if (!hasNotificationsContent && (!breadcrumbs || isMobile) && !contentHeader && dynamicOverlapHeight <= 0) {
+  if (!hasNotificationsContent && (!breadcrumbs || isMobile) && !isDynamicOverlapSet) {
     return null;
   }
 

src/app-layout/visual-refresh/context.tsx

@@ -30,6 +30,7 @@ import { warnOnce } from '@cloudscape-design/component-toolkit/internal';
 import useResize from '../utils/use-resize';
 import styles from './styles.css.js';
 import { useContainerQuery } from '@cloudscape-design/component-toolkit';
+import customCssProps from '../../internal/generated/custom-css-properties';
 
 interface AppLayoutInternals extends AppLayoutProps {
   activeDrawerId?: string | null;
@@ -40,7 +41,6 @@ interface AppLayoutInternals extends AppLayoutProps {
   drawerRef: React.Ref<HTMLElement>;
   resizeHandle: React.ReactElement;
   drawersTriggerCount: number;
-  dynamicOverlapHeight: number;
   handleDrawersClick: (activeDrawerId: string | null, skipFocusControl?: boolean) => void;
   handleSplitPanelClick: () => void;
   handleNavigationClick: (isOpen: boolean) => void;
@@ -52,6 +52,8 @@ interface AppLayoutInternals extends AppLayoutProps {
   hasNotificationsContent: boolean;
   hasOpenDrawer?: boolean;
   hasStickyBackground: boolean;
+  isDynamicOverlapDisabled: boolean;
+  isDynamicOverlapSet: boolean;
   isMobile: boolean;
   isNavigationOpen: boolean;
   isSplitPanelForcedPosition: boolean;
@@ -136,7 +138,8 @@ export const AppLayoutInternalsProvider = React.forwardRef(
      * If a child component utilizes a sticky header the hasStickyBackground property will determine
      * if the background remains in the same vertical position.
      */
-    const [dynamicOverlapHeight, setDynamicOverlapHeight] = useState(0);
+    const [isDynamicOverlapSet, setIsDynamicOverlapSet] = useState(false);
+    const [isDynamicOverlapDisabled, setIsDynamicOverlapDisabled] = useState(true);
     const [hasStickyBackground, setHasStickyBackground] = useState(false);
 
     /**
@@ -487,6 +490,38 @@ export const AppLayoutInternalsProvider = React.forwardRef(
     const mainElement = useRef<HTMLDivElement>(null);
     const [mainOffsetLeft, setMainOffsetLeft] = useState(0);
 
+    const updateDynamicOverlapHeight = useCallback(
+      (height: number) => {
+        /**
+         * The disableContentHeaderOverlap property is absolute and will always disable the overlap
+         * if it is set to true. If there is no contentHeader then the overlap should be disabled
+         * unless there is a dynamicOverlapHeight. The dynamicOverlapHeight property is set by a
+         * component in the content slot that needs to manually control the overlap height.
+         */
+        const isOverlapSet = !!props.contentHeader || height > 0;
+        const isOverlapDisabled = props.disableContentHeaderOverlap || !isOverlapSet;
+        setIsDynamicOverlapSet(isOverlapSet);
+        setIsDynamicOverlapDisabled(isOverlapDisabled);
+
+        /**
+         * React 18 will trigger a paint before the state is correctly updated
+         * (see https://github.com/facebook/react/issues/24331).
+         * To work around this, we bypass React state updates and imperatively update the custom property on the DOM.
+         * An alternative would be to use `queueMicrotask` and `flushSync` in the ResizeObserver callback,
+         * but that would have some performance impact as it would delay the render.
+         * Using React state for `isDynamicOverlapSet` and `isDynamicOverlapDisabled` is less problematic
+         * because they will rarely change within the lifecycle of an application.
+         */
+        const element = typeof layoutElement === 'function' ? layoutElement(null) : layoutElement?.current;
+        if (isOverlapDisabled || height <= 0) {
+          element?.style.removeProperty(customCssProps.overlapHeight);
+        } else {
+          element?.style.setProperty(customCssProps.overlapHeight, `${height}px`);
+        }
+      },
+      [layoutElement, props.contentHeader, props.disableContentHeaderOverlap]
+    );
+
     useLayoutEffect(
       function handleMainOffsetLeft() {
         setMainOffsetLeft(mainElement?.current?.offsetLeft ?? 0);
@@ -600,7 +635,6 @@ export const AppLayoutInternalsProvider = React.forwardRef(
           drawerRef,
           resizeHandle,
           drawersTriggerCount,
-          dynamicOverlapHeight,
           headerHeight,
           footerHeight,
           hasDefaultToolsWidth,
@@ -616,6 +650,8 @@ export const AppLayoutInternalsProvider = React.forwardRef(
           hasStickyBackground,
           isMobile,
           isNavigationOpen: isNavigationOpen ?? false,
+          isDynamicOverlapDisabled,
+          isDynamicOverlapSet,
           isSplitPanelForcedPosition,
           isSplitPanelOpen,
           isToolsOpen,
@@ -660,7 +696,7 @@ export const AppLayoutInternalsProvider = React.forwardRef(
             setHasStickyBackground,
           }}
         >
-          <DynamicOverlapContext.Provider value={setDynamicOverlapHeight}>{children}</DynamicOverlapContext.Provider>
+          <DynamicOverlapContext.Provider value={updateDynamicOverlapHeight}>{children}</DynamicOverlapContext.Provider>
         </AppLayoutContext.Provider>
       </AppLayoutInternalsContext.Provider>
     );

src/app-layout/visual-refresh/layout.tsx

@@ -23,15 +23,14 @@ export default function Layout({ children }: LayoutProps) {
     contentHeader,
     contentType,
     disableBodyScroll,
-    disableContentHeaderOverlap,
     disableContentPaddings,
     drawersTriggerCount,
-    dynamicOverlapHeight,
     footerHeight,
     hasNotificationsContent,
     hasStickyBackground,
     hasOpenDrawer,
     headerHeight,
+    isDynamicOverlapDisabled,
     isMobile,
     isNavigationOpen,
     layoutElement,
@@ -53,14 +52,6 @@ export default function Layout({ children }: LayoutProps) {
   const hasContentGapLeft = isNavigationOpen || navigationHide;
   const hasContentGapRight = drawersTriggerCount <= 0 || hasOpenDrawer;
 
-  /**
-   * The disableContentHeaderOverlap property is absolute and will always disable the overlap
-   * if it is set to true. If there is no contentHeader then the overlap should be disabled
-   * unless there is a dynamicOverlapHeight. The dynamicOverlapHeight property is set by a
-   * component in the content slot that needs to manually control the overlap height.
-   */
-  const isOverlapDisabled = disableContentHeaderOverlap || (!contentHeader && dynamicOverlapHeight <= 0);
-
   return (
     <main
       className={clsx(
@@ -80,7 +71,7 @@ export default function Layout({ children }: LayoutProps) {
           [styles['has-split-panel']]: splitPanelDisplayed,
           [styles['has-sticky-background']]: hasStickyBackground,
           [styles['has-sticky-notifications']]: stickyNotifications && hasNotificationsContent,
-          [styles['is-overlap-disabled']]: isOverlapDisabled,
+          [styles['is-overlap-disabled']]: isDynamicOverlapDisabled,
         },
         testutilStyles.root
       )}
@@ -93,8 +84,6 @@ export default function Layout({ children }: LayoutProps) {
         ...(maxContentWidth && { [customCssProps.maxContentWidth]: `${maxContentWidth}px` }),
         ...(minContentWidth && { [customCssProps.minContentWidth]: `${minContentWidth}px` }),
         [customCssProps.notificationsHeight]: `${notificationsHeight}px`,
-        ...(!isOverlapDisabled &&
-          dynamicOverlapHeight > 0 && { [customCssProps.overlapHeight]: `${dynamicOverlapHeight}px` }),
       }}
     >
       {children}
@@ -104,8 +93,8 @@ export default function Layout({ children }: LayoutProps) {
 
 /*
 The Notifications, Breadcrumbs, Header, and Main are all rendered in the center
-column of the grid layout. Any of these could be the first child to render in the 
-content area if the previous siblings do not exist. The grid gap before the first 
+column of the grid layout. Any of these could be the first child to render in the
+content area if the previous siblings do not exist. The grid gap before the first
 child will be different to ensure vertical alignment with the trigger buttons.
 */
 function getContentFirstChild(

src/internal/hooks/container-queries/use-resize-observer.ts

@@ -4,6 +4,7 @@ import { ResizeObserver, ResizeObserverEntry } from '@juggle/resize-observer';
 import React, { useEffect, useLayoutEffect } from 'react';
 import { useStableEventHandler } from '../use-stable-event-handler';
 import { ContainerQueryEntry } from '@cloudscape-design/component-toolkit';
+import { convertResizeObserverEntry } from './utils';
 
 type ElementReference = (() => Element | null) | React.RefObject<Element>;
 
@@ -58,13 +59,3 @@ export function useResizeObserver(elementRef: ElementReference, onObserve: (entr
     }
   }, [elementRef, stableOnObserve]);
 }
-
-function convertResizeObserverEntry(entry: ResizeObserverEntry): ContainerQueryEntry {
-  return {
-    target: entry.target,
-    contentBoxWidth: entry.contentBoxSize[0].inlineSize,
-    contentBoxHeight: entry.contentBoxSize[0].blockSize,
-    borderBoxWidth: entry.borderBoxSize[0].inlineSize,
-    borderBoxHeight: entry.borderBoxSize[0].blockSize,
-  };
-}

src/internal/hooks/container-queries/utils.ts

@@ -0,0 +1,14 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { ResizeObserverEntry } from '@juggle/resize-observer';
+import { ContainerQueryEntry } from '@cloudscape-design/component-toolkit';
+
+export function convertResizeObserverEntry(entry: ResizeObserverEntry): ContainerQueryEntry {
+  return {
+    target: entry.target,
+    contentBoxWidth: entry.contentBoxSize[0].inlineSize,
+    contentBoxHeight: entry.contentBoxSize[0].blockSize,
+    borderBoxWidth: entry.borderBoxSize[0].inlineSize,
+    borderBoxHeight: entry.borderBoxSize[0].blockSize,
+  };
+}

src/internal/hooks/use-dynamic-overlap/__tests__/use-dynamic-overlap.test.tsx

@@ -6,9 +6,9 @@ import { render, screen } from '@testing-library/react';
 import { useDynamicOverlap } from '../../../../../lib/components/internal/hooks/use-dynamic-overlap';
 import { DynamicOverlapContext } from '../../../../../lib/components/internal/context/dynamic-overlap-context';
 
-jest.mock('@cloudscape-design/component-toolkit', () => ({
-  ...jest.requireActual('@cloudscape-design/component-toolkit'),
-  useContainerQuery: () => [800, () => {}],
+jest.mock('../../../../../lib/components/internal/hooks/container-queries/utils', () => ({
+  ...jest.requireActual('../../../../../lib/components/internal/hooks/container-queries/utils'),
+  convertResizeObserverEntry: () => ({ contentBoxHeight: 800 }),
 }));
 
 function renderApp(children: React.ReactNode) {