Merge pull request #355 from eccenca/feature/contextOverlayImprovePlaceholderProcess-CMEM-7032

haschek · web-flow · commit 4125ac2102b0 · 2025-11-26T14:28:23.000+01:00
Improve placeholder replacement for ContextOverlay/ContextMenu (CMEM-7032)
diff --git a/src/components/ContextOverlay/ContextOverlay.tsx b/src/components/ContextOverlay/ContextOverlay.tsx
@@ -2,6 +2,7 @@ import React from "react";
 import {
     Classes as BlueprintClasses,
     Popover as BlueprintPopover,
+    PopoverInteractionKind as InteractionKind,
     PopoverProps as BlueprintPopoverProps,
     Utils as BlueprintUtils,
 } from "@blueprintjs/core";
@@ -37,9 +38,10 @@ export const ContextOverlay = ({
     usePlaceholder = false,
     ...otherPopoverProps
 }: ContextOverlayProps) => {
-    const placeholderRef = React.useRef(null);
-    const eventMemory = React.useRef<undefined | "afterhover" | "afterfocus">(undefined);
+    const placeholderRef = React.useRef<HTMLElement>(null);
+    const eventMemory = React.useRef<undefined | "mouseenter" | "focusin" | "click">(undefined);
     const swapDelay = React.useRef<null | NodeJS.Timeout>(null);
+    const interactionKind = React.useRef<InteractionKind>(otherPopoverProps.interactionKind ?? InteractionKind.CLICK);
     const swapDelayTime = 15;
     const [placeholder, setPlaceholder] = React.useState<boolean>(
         // use placeholder only for "simple" overlays without special states
@@ -50,37 +52,85 @@ export const ContextOverlay = ({
             usePlaceholder
     );
 
+    const swap = (ev: MouseEvent | globalThis.FocusEvent) => {
+        const waitForClick =
+            interactionKind.current === InteractionKind.CLICK ||
+            interactionKind.current === InteractionKind.CLICK_TARGET_ONLY;
+
+        if (swapDelay.current) {
+            clearTimeout(swapDelay.current);
+        }
+
+        const replacePlaceholder = () => {
+            eventMemory.current = ev.type as "mouseenter" | "focusin" | "click";
+            setPlaceholder(false);
+        };
+
+        if (waitForClick) {
+            ev.stopImmediatePropagation();
+            replacePlaceholder();
+            return;
+        }
+
+        swapDelay.current = setTimeout(
+            replacePlaceholder,
+            // we delay the swap for hover/focus to prevent unwanted effects
+            // (e.g. event hickup after replacing elements when it is not really necessary)
+            swapDelayTime
+        );
+    };
+
     React.useEffect(() => {
+        interactionKind.current = otherPopoverProps.interactionKind ?? InteractionKind.CLICK;
+        const waitForClick =
+            interactionKind.current === InteractionKind.CLICK ||
+            interactionKind.current === InteractionKind.CLICK_TARGET_ONLY;
+        const removeEvents = () => {
+            if (placeholderRef.current) {
+                placeholderRef.current.removeEventListener("click", swap);
+                placeholderRef.current.removeEventListener("mouseenter", swap);
+                placeholderRef.current.removeEventListener("focusin", swap);
+            }
+            return;
+        };
         if (placeholderRef.current) {
-            const swap = (ev: MouseEvent | globalThis.FocusEvent) => {
-                if (swapDelay.current) {
-                    clearTimeout(swapDelay.current);
-                }
-                swapDelay.current = setTimeout(() => {
-                    // we delay the swap to prevent unwanted effects
-                    // (e.g. event hickup after replacing elements when it is not really necessary)
-                    eventMemory.current = ev.type === "focusin" ? "afterfocus" : "afterhover";
-                    setPlaceholder(false);
-                }, swapDelayTime);
-            };
-            (placeholderRef.current as HTMLElement).addEventListener("mouseenter", swap);
-            (placeholderRef.current as HTMLElement).addEventListener("focusin", swap);
+            removeEvents(); // remove events in case of interaction kind changed during existence
+            if (waitForClick) {
+                placeholderRef.current.addEventListener("click", swap);
+            } else {
+                placeholderRef.current.addEventListener("mouseenter", swap);
+                placeholderRef.current.addEventListener("focusin", swap);
+            }
             return () => {
-                if (placeholderRef.current) {
-                    (placeholderRef.current as HTMLElement).removeEventListener("mouseenter", swap);
-                    (placeholderRef.current as HTMLElement).removeEventListener("focusin", swap);
-                }
+                removeEvents();
             };
         }
         return () => {};
-    }, [!!placeholderRef.current]);
+    }, [!!placeholderRef.current, otherPopoverProps.interactionKind]);
 
     const refocus = React.useCallback((node) => {
-        if (eventMemory.current === "afterfocus" && node) {
-            const target = node.targetRef.current.children[0];
-            if (target) {
+        const target = node?.targetRef.current.children[0];
+        if (!eventMemory.current || !target) {
+            return;
+        }
+        switch (eventMemory.current) {
+            case "focusin":
                 target.focus();
-            }
+                break;
+            case "click":
+                target.click();
+                break;
+            case "mouseenter":
+                // re-check if the cursor is still over the element after swapping the placeholder before triggering the event to bubble up
+                (target as HTMLElement).addEventListener(
+                    "mouseover",
+                    () => (target as HTMLElement).dispatchEvent(new MouseEvent("mouseover", { bubbles: true })),
+                    {
+                        capture: true,
+                        once: true,
+                    }
+                );
+                break;
         }
     }, []);
 
diff --git a/src/components/ContextOverlay/tests/ContextMenu.test.tsx b/src/components/ContextOverlay/tests/ContextMenu.test.tsx
@@ -0,0 +1,43 @@
+import React from "react";
+import { fireEvent, render, screen } from "@testing-library/react";
+
+import "@testing-library/jest-dom";
+
+import { CLASSPREFIX as eccgui } from "../../../configuration/constants";
+
+import ContextMenu from "./../ContextMenu";
+import { Default as ContextMenuStory } from "./../ContextMenu.stories";
+
+const overlayWrapper = `${eccgui}-contextoverlay`;
+const placeholderClass = `${overlayWrapper}__wrapper--placeholder`;
+
+const checkForPlaceholderClass = (container: HTMLElement, tobe: number) => {
+    expect(container.getElementsByClassName(placeholderClass).length).toBe(tobe);
+};
+
+describe("ContextMenu", () => {
+    it("should render placeholder automatically", () => {
+        const { container } = render(<ContextMenu {...ContextMenuStory.args} />);
+        checkForPlaceholderClass(container, 1);
+    });
+    it("should not render placeholder when `preventPlaceholder===true`", () => {
+        const { container } = render(<ContextMenu {...ContextMenuStory.args} preventPlaceholder={true} />);
+        checkForPlaceholderClass(container, 0);
+    });
+    it("should render placeholder when `preventPlaceholder===false`", () => {
+        const { container } = render(<ContextMenu {...ContextMenuStory.args} preventPlaceholder={false} />);
+        checkForPlaceholderClass(container, 1);
+    });
+    it("if no placeholder is used the menu should be displayed on click", async () => {
+        const { container } = render(<ContextMenu {...ContextMenuStory.args} preventPlaceholder={true} />);
+        checkForPlaceholderClass(container, 0);
+        fireEvent.click(container.getElementsByClassName(overlayWrapper)[0]);
+        expect(await screen.findByText("First option")).toBeVisible();
+    });
+    it("if placeholder is used the menu should be displayed on click", async () => {
+        const { container } = render(<ContextMenu {...ContextMenuStory.args} preventPlaceholder={false} />);
+        checkForPlaceholderClass(container, 1);
+        fireEvent.click(container.getElementsByClassName(overlayWrapper)[0]);
+        expect(await screen.findByText("First option")).toBeVisible();
+    });
+});
diff --git a/src/components/ContextOverlay/tests/ContextOverlay.test.tsx b/src/components/ContextOverlay/tests/ContextOverlay.test.tsx
@@ -0,0 +1,71 @@
+import React from "react";
+import { PopoverInteractionKind } from "@blueprintjs/core";
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+
+import "@testing-library/jest-dom";
+
+import { CLASSPREFIX as eccgui } from "../../../configuration/constants";
+
+import ContextOverlay from "./../ContextOverlay";
+import { Default as ContextOverlayStory } from "./../ContextOverlay.stories";
+
+const overlayWrapper = `${eccgui}-contextoverlay`;
+const placeholderClass = `${overlayWrapper}__wrapper--placeholder`;
+
+const checkForPlaceholderClass = (container: HTMLElement, tobe: number) => {
+    expect(container.getElementsByClassName(placeholderClass).length).toBe(tobe);
+};
+
+describe("ContextOverlay", () => {
+    it("should not render placeholder automatically", () => {
+        const { container } = render(<ContextOverlay {...ContextOverlayStory.args} />);
+        checkForPlaceholderClass(container, 0);
+    });
+    it("should render placeholder when `usePlaceholder===true`", () => {
+        const { container } = render(<ContextOverlay {...ContextOverlayStory.args} usePlaceholder={true} />);
+        checkForPlaceholderClass(container, 1);
+    });
+    it("should render no placeholder when `usePlaceholder===false`", () => {
+        const { container } = render(<ContextOverlay {...ContextOverlayStory.args} usePlaceholder={false} />);
+        checkForPlaceholderClass(container, 0);
+    });
+    it("if no placeholder is used the overlay should be displayed on click", async () => {
+        const { container } = render(<ContextOverlay {...ContextOverlayStory.args} usePlaceholder={false} />);
+        fireEvent.click(container.getElementsByClassName(overlayWrapper)[0]);
+        expect(await screen.findByText("Overlay:")).toBeVisible();
+    });
+    it("if no placeholder is used the overlay should be displayed on hover (hover interactionKind)", async () => {
+        const { container } = render(
+            <ContextOverlay
+                {...ContextOverlayStory.args}
+                usePlaceholder={false}
+                interactionKind={PopoverInteractionKind.HOVER}
+            />
+        );
+        fireEvent.mouseEnter(container.getElementsByClassName(overlayWrapper)[0]);
+        expect(await screen.findByText("Overlay:")).toBeVisible();
+    });
+    it("if placeholder is used the overlay should be displayed on click", async () => {
+        const { container } = render(<ContextOverlay {...ContextOverlayStory.args} usePlaceholder={true} />);
+        fireEvent.click(container.getElementsByClassName(overlayWrapper)[0]);
+        expect(await screen.findByText("Overlay:")).toBeVisible();
+    });
+    it("if placeholder is used the overlay should be displayed on hover (hover interactionKind)", async () => {
+        const { container } = render(
+            <ContextOverlay
+                {...ContextOverlayStory.args}
+                usePlaceholder={true}
+                interactionKind={PopoverInteractionKind.HOVER}
+            />
+        );
+        checkForPlaceholderClass(container, 1);
+        fireEvent.mouseEnter(container.getElementsByClassName(overlayWrapper)[0]);
+        await waitFor(async () => {
+            expect(screen.queryByDisplayValue("Overlay:")).toBeNull();
+            checkForPlaceholderClass(container, 0);
+            // we need to emulate another mouseover to simulate real user behaviour
+            fireEvent.mouseOver(container.getElementsByClassName(overlayWrapper)[0]);
+            expect(await screen.findByText("Overlay:")).toBeVisible();
+        });
+    });
+});
