fix: unify z-index logic and ensure it's correct for all isPushed and maskProps combinations

tkajtoch · tkajtoch · commit e14ab4bdda64 · 2025-11-04T02:06:48.000+01:00
diff --git a/packages/eui/src/components/flyout/_flyout_overlay.tsx b/packages/eui/src/components/flyout/_flyout_overlay.tsx
@@ -6,35 +6,29 @@
  * Side Public License, v 1.
  */
 
-import React, { PropsWithChildren } from 'react';
+import React, { PropsWithChildren, useMemo } from 'react';
 import { css, cx } from '@emotion/css';
-import type { EuiFlyoutComponentProps } from './flyout.component';
 import { EuiOverlayMask } from '../overlay_mask';
 import { EuiPortal } from '../portal';
-import { useEuiMemoizedStyles, type UseEuiTheme } from '../../services';
+import type { EuiFlyoutComponentProps } from './flyout.component';
 
 export interface EuiFlyoutOverlayProps extends PropsWithChildren {
   hasOverlayMask: boolean;
   maskProps: EuiFlyoutComponentProps['maskProps'];
   isPushed: boolean;
+  maskZIndex: number;
 }
 
-const getEuiFlyoutOverlayStyles = ({ euiTheme }: UseEuiTheme) => {
-  // TODO(tkajtoch): This should likely depend on maskProps.headerZIndexLocation
-  // in cases where the mask has z-index 6000
-  const maskLevel = Number(euiTheme.levels.flyout) - 1;
-
-  return {
-    overlayMask: css`
-      /*
-      This needs to have !important to override the default EuiOverlayMask
-      z-index based on the headerZindexLocation prop. Using the style attribute
-      doesn't work since EuiOverlayMask requires a string style prop that
-      causes React errors in the test environment.
-      */
-      z-index: ${maskLevel} !important;
-    `,
-  };
+const getEuiFlyoutOverlayStyles = (zIndex: number) => {
+  /*
+  This needs to have !important to override the default EuiOverlayMask
+  z-index based on the headerZindexLocation prop. Using the style attribute
+  doesn't work since EuiOverlayMask requires a string style prop that
+  causes React errors in the test environment.
+  */
+  return css`
+    z-index: ${zIndex} !important;
+  `;
 };
 
 /**
@@ -50,21 +44,28 @@ export const EuiFlyoutOverlay = ({
   isPushed,
   maskProps,
   hasOverlayMask,
+  maskZIndex,
 }: EuiFlyoutOverlayProps) => {
-  const styles = useEuiMemoizedStyles(getEuiFlyoutOverlayStyles);
+  const styles = useMemo(
+    () => getEuiFlyoutOverlayStyles(maskZIndex),
+    [maskZIndex]
+  );
+
   let content = children;
 
   if (!isPushed || hasOverlayMask) {
     content = <EuiPortal>{content}</EuiPortal>;
   }
 
+  const classes = cx(maskProps?.className, styles);
+
   return (
     <>
       {hasOverlayMask && (
         <EuiOverlayMask
           headerZindexLocation="below"
           {...maskProps}
-          className={cx(maskProps?.className, styles.overlayMask)}
+          className={classes}
         />
       )}
       {content}
diff --git a/packages/eui/src/components/flyout/flyout.component.tsx b/packages/eui/src/components/flyout/flyout.component.tsx
@@ -70,6 +70,7 @@ import { EuiFlyoutOverlay } from './_flyout_overlay';
 import { EuiFlyoutResizeButton } from './_flyout_resize_button';
 import { useEuiFlyoutResizable } from './use_flyout_resizable';
 import type { EuiFlyoutCloseEvent } from './types';
+import { useEuiFlyoutZIndex } from './use_flyout_z_index';
 
 interface _EuiFlyoutComponentProps {
   /**
@@ -403,6 +404,11 @@ export const EuiFlyoutComponent = forwardRef(
 
     const siblingFlyoutWidth = useFlyoutWidth(siblingFlyoutId);
 
+    const { flyoutZIndex, maskZIndex } = useEuiFlyoutZIndex({
+      maskProps,
+      isPushed,
+    });
+
     /**
      * Set inline styles
      */
@@ -412,7 +418,8 @@ export const EuiFlyoutComponent = forwardRef(
         layoutMode,
         siblingFlyoutId,
         siblingFlyoutWidth || null,
-        maxWidth
+        maxWidth,
+        flyoutZIndex
       );
 
       return { ...style, ...composedStyles };
@@ -423,6 +430,7 @@ export const EuiFlyoutComponent = forwardRef(
       siblingFlyoutId,
       siblingFlyoutWidth,
       maxWidth,
+      flyoutZIndex,
     ]);
 
     const styles = useEuiMemoizedStyles(euiFlyoutStyles);
@@ -579,6 +587,7 @@ export const EuiFlyoutComponent = forwardRef(
       <EuiFlyoutOverlay
         hasOverlayMask={hasOverlayMask}
         isPushed={isPushed}
+        maskZIndex={maskZIndex}
         maskProps={{
           ...maskProps,
           maskRef: maskCombinedRefs,
diff --git a/packages/eui/src/components/flyout/flyout.styles.ts b/packages/eui/src/components/flyout/flyout.styles.ts
@@ -80,7 +80,6 @@ export const euiFlyoutStyles = (euiThemeContext: UseEuiTheme) => {
       ${logicalCSS('bottom', 0)}
       ${logicalCSS('top', 'var(--euiFixedHeadersOffset, 0)')}
       ${logicalCSS('height', 'inherit')}
-      z-index: ${euiTheme.levels.flyout};
       background: ${euiTheme.colors.backgroundBasePlain};
       display: flex;
       flex-direction: column;
@@ -361,7 +360,8 @@ export const composeFlyoutInlineStyles = (
   layoutMode: 'side-by-side' | 'stacked',
   siblingFlyoutId: string | null,
   siblingFlyoutWidth: number | null,
-  maxWidth: boolean | number | string | undefined
+  maxWidth: boolean | number | string | undefined,
+  zIndex: number
 ): React.CSSProperties => {
   // Handle custom width values (non-named sizes)
   const customWidthStyles = !isEuiFlyoutSizeNamed(size)
@@ -433,5 +433,6 @@ export const composeFlyoutInlineStyles = (
     ...dynamicStyles,
     ...minWidthOverride,
     ...(finalMaxWidth ? { maxWidth: finalMaxWidth } : {}),
+    zIndex,
   });
 };
diff --git a/packages/eui/src/components/flyout/use_flyout_z_index.test.ts b/packages/eui/src/components/flyout/use_flyout_z_index.test.ts
@@ -0,0 +1,50 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import { renderHook } from '../../test/rtl/render_hook';
+import { UseEuiFlyoutZIndex, useEuiFlyoutZIndex } from './use_flyout_z_index';
+
+describe('useEuiFlyoutZIndex', () => {
+  const render = (initialProps: UseEuiFlyoutZIndex) =>
+    renderHook((props: UseEuiFlyoutZIndex) => useEuiFlyoutZIndex(props), {
+      initialProps,
+    });
+
+  it('returns flyout level based z-index values when isPushed = true', () => {
+    const { result, rerender } = render({ isPushed: true });
+    expect(result.current.flyoutZIndex).toEqual(1000);
+    expect(result.current.maskZIndex).toEqual(999);
+
+    rerender({ isPushed: true, maskProps: { headerZindexLocation: 'above' } });
+    expect(result.current.flyoutZIndex).toEqual(1000);
+    expect(result.current.maskZIndex).toEqual(999);
+
+    rerender({ isPushed: true, maskProps: { headerZindexLocation: 'below' } });
+    expect(result.current.flyoutZIndex).toEqual(1000);
+    expect(result.current.maskZIndex).toEqual(999);
+  });
+
+  it('returns flyout level based z-index values when maskProps.headerZindexLocation != "above"', () => {
+    const { result, rerender } = render({ isPushed: false, maskProps: {} });
+    expect(result.current.flyoutZIndex).toEqual(1000);
+    expect(result.current.maskZIndex).toEqual(999);
+
+    rerender({ isPushed: false, maskProps: { headerZindexLocation: 'below' } });
+    expect(result.current.flyoutZIndex).toEqual(1000);
+    expect(result.current.maskZIndex).toEqual(999);
+  });
+
+  it('returns mask level based z-index values when maskProps.headerZindexLocation = "above"', () => {
+    const { result } = render({
+      isPushed: false,
+      maskProps: { headerZindexLocation: 'above' },
+    });
+    expect(result.current.flyoutZIndex).toEqual(6000);
+    expect(result.current.maskZIndex).toEqual(5999);
+  });
+});
diff --git a/packages/eui/src/components/flyout/use_flyout_z_index.ts b/packages/eui/src/components/flyout/use_flyout_z_index.ts
@@ -0,0 +1,51 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import type { CSSProperties } from 'react';
+import { useEuiTheme } from '../../services';
+import type { EuiOverlayMaskProps } from '../overlay_mask';
+
+/**
+ * @internal
+ */
+export interface UseEuiFlyoutZIndex {
+  maskProps?: EuiOverlayMaskProps;
+  isPushed: boolean;
+}
+
+const calculateZIndex = (initialValue: CSSProperties['zIndex']) => {
+  const valueAsNumber = Number(initialValue);
+
+  return {
+    flyoutZIndex: valueAsNumber,
+    maskZIndex: valueAsNumber - 1,
+  };
+};
+
+/**
+ * TODO: Calculate z-index values so that the latest flyout is always on top
+ * https://github.com/elastic/eui/issues/9160
+ * @internal
+ */
+export const useEuiFlyoutZIndex = ({
+  maskProps,
+  isPushed,
+}: UseEuiFlyoutZIndex) => {
+  const { euiTheme } = useEuiTheme();
+
+  // The default headerZindexLocation for EuiFlyout is "below"
+  // which is different from what EuiOverlayMask fallbacks to - see
+  // _flyout_overlay.tsx.
+  // We set z-index to mask level only when explicitly overridden
+  // via the maskProps prop
+  if (!isPushed && maskProps?.headerZindexLocation === 'above') {
+    return calculateZIndex(euiTheme.levels.mask);
+  }
+
+  return calculateZIndex(euiTheme.levels.flyout);
+};
