feat(overflow-menu): support e.preventDefault on item click (#2360)

Author: metonym

COMPONENT_INDEX.md

@@ -2677,10 +2677,10 @@ None.
 
 ### Events
 
-| Event name | Type      | Detail | Description |
-| :--------- | :-------- | :----- | :---------- |
-| click      | forwarded | --     | --          |
-| keydown    | forwarded | --     | --          |
+| Event name | Type       | Detail                  | Description |
+| :--------- | :--------- | :---------------------- | :---------- |
+| click      | dispatched | <code>MouseEvent</code> | --          |
+| keydown    | forwarded  | --                      | --          |
 
 ## `Pagination`
 

docs/src/COMPONENT_API.json

@@ -10639,9 +10639,9 @@
       ],
       "events": [
         {
-          "type": "forwarded",
+          "type": "dispatched",
           "name": "click",
-          "element": "a"
+          "detail": "MouseEvent"
         },
         {
           "type": "forwarded",

docs/src/pages/components/OverflowMenu.svx

@@ -116,4 +116,19 @@ Set `disabled` to `true` to disable menu items. Use `hasDivider` to add visual s
     text="API documentation"
   />
   <OverflowMenuItem hasDivider danger text="Delete service" />
-</OverflowMenu>
+</OverflowMenu>
+
+## Prevent menu from closing
+
+Use `preventDefault()` on individual `OverflowMenuItem` click events to prevent the menu from closing when that item is clicked. This is useful for scenarios where you want to keep the menu open after performing an action.
+
+<OverflowMenu>
+  <OverflowMenuItem
+    text="Show all files"
+    on:click={(e) => {
+      // Prevent menu from closing for this item.
+      e.preventDefault();
+    }}
+  />
+  <OverflowMenuItem text="Close menu" />
+</OverflowMenu>

src/OverflowMenu/OverflowMenu.svelte

@@ -105,8 +105,14 @@
   const update = (id, item) => {
     currentId.set(id);
 
-    dispatch("close", { index: item.index, text: item.text });
-    open = false;
+    const shouldContinue = dispatch(
+      "close",
+      { index: item.index, text: item.text },
+      { cancelable: true },
+    );
+    if (shouldContinue) {
+      open = false;
+    }
   };
 
   /**
@@ -199,8 +205,10 @@
   on:click={({ target }) => {
     if (buttonRef && buttonRef.contains(target)) return;
     if (menuRef && !menuRef.contains(target)) {
-      dispatch("close");
-      open = false;
+      const shouldContinue = dispatch("close", null, { cancelable: true });
+      if (shouldContinue) {
+        open = false;
+      }
     }
   }}
 />
@@ -224,7 +232,12 @@
   on:click={({ target }) => {
     if (!(menuRef && menuRef.contains(target))) {
       open = !open;
-      if (!open) dispatch("close");
+      if (!open) {
+        const shouldContinue = dispatch("close", null, { cancelable: true });
+        if (!shouldContinue) {
+          open = true;
+        }
+      }
     }
   }}
   on:mouseover
@@ -237,9 +250,11 @@
         e.preventDefault();
       } else if (e.key === "Escape") {
         e.stopPropagation();
-        dispatch("close");
-        open = false;
-        buttonRef.focus();
+        const shouldContinue = dispatch("close", null, { cancelable: true });
+        if (shouldContinue) {
+          open = false;
+          buttonRef.focus();
+        }
       }
     }
   }}

src/OverflowMenu/OverflowMenuItem.svelte

@@ -1,4 +1,8 @@
 <script>
+  /**
+   * @event {MouseEvent} click
+   */
+
   /**
    * Specify the item text.
    * Alternatively, use the default slot
@@ -29,8 +33,9 @@
   /** Obtain a reference to the HTML element */
   export let ref = null;
 
-  import { afterUpdate, getContext } from "svelte";
+  import { afterUpdate, createEventDispatcher, getContext } from "svelte";
 
+  const dispatch = createEventDispatcher();
   const { focusedId, add, update, change, items } = getContext("OverflowMenu");
 
   $: item = $items.find((_) => _.id === id);
@@ -52,6 +57,17 @@
     href: href ? href : undefined,
     title: requireTitle ? ($$slots.default ? undefined : text) : undefined,
   };
+
+  function handleClick(e) {
+    e.stopPropagation();
+
+    const shouldContinue = dispatch("click", e, { cancelable: true });
+
+    // Only update (close menu) if preventDefault was not called.
+    if (shouldContinue) {
+      update(id, item);
+    }
+  }
 </script>
 
 <li
@@ -69,11 +85,7 @@
     <a
       bind:this={ref}
       {...buttonProps}
-      on:click
-      on:click={(e) => {
-        e.stopPropagation();
-        update(id, item);
-      }}
+      on:click={handleClick}
       on:keydown
       on:keydown={({ key }) => {
         if (key === "ArrowDown") {
@@ -93,11 +105,7 @@
     <button
       bind:this={ref}
       {...buttonProps}
-      on:click
-      on:click={(e) => {
-        e.stopPropagation();
-        update(id, item);
-      }}
+      on:click={handleClick}
       on:keydown
       on:keydown={({ key }) => {
         if (key === "ArrowDown") {

tests/OverflowMenu/OverflowMenu.preventDefault.test.svelte

@@ -0,0 +1,31 @@
+<script lang="ts">
+  import { OverflowMenu, OverflowMenuItem } from "carbon-components-svelte";
+</script>
+
+<OverflowMenu
+  on:close={(e) => {
+    console.log("close", e.detail);
+  }}
+>
+  <OverflowMenuItem
+    text="Manage credentials"
+    on:click={(e) => {
+      console.log("click", "Manage credentials");
+      e.preventDefault(); // Prevent menu from closing
+    }}
+  />
+  <OverflowMenuItem
+    href="https://cloud.ibm.com/docs/api-gateway/"
+    text="API documentation"
+    on:click={(e) => {
+      console.log("click", "API documentation");
+    }}
+  />
+  <OverflowMenuItem
+    danger
+    text="Delete service"
+    on:click={(e) => {
+      console.log("click", "Delete service");
+    }}
+  />
+</OverflowMenu>

tests/OverflowMenu/OverflowMenu.test.ts

@@ -1,5 +1,6 @@
 import { render, screen } from "@testing-library/svelte";
 import { user } from "../setup-tests";
+import OverflowMenuPreventDefault from "./OverflowMenu.preventDefault.test.svelte";
 import OverflowMenu from "./OverflowMenu.test.svelte";
 
 describe("OverflowMenu", () => {
@@ -287,4 +288,39 @@ describe("OverflowMenu", () => {
 
     expect(spy).toHaveBeenCalledWith("close", null);
   });
+
+  it("supports preventDefault on item to prevent menu from closing", async () => {
+    const consoleLog = vi.spyOn(console, "log");
+    render(OverflowMenuPreventDefault);
+
+    const menuButton = screen.getByRole("button");
+    await user.click(menuButton);
+    expect(menuButton).toHaveAttribute("aria-expanded", "true");
+
+    const menuItems = screen.getAllByRole("menuitem");
+    await user.click(menuItems[0]);
+
+    expect(consoleLog).toHaveBeenCalledWith("click", "Manage credentials");
+    expect(consoleLog).not.toHaveBeenCalledWith("close", {
+      index: 0,
+      text: "Manage credentials",
+    });
+
+    expect(menuButton).toHaveAttribute("aria-expanded", "true");
+    expect(screen.queryByRole("menu")).toBeInTheDocument();
+  });
+
+  it("closes menu normally when preventDefault is not called", async () => {
+    render(OverflowMenu);
+
+    const menuButton = screen.getByRole("button");
+    await user.click(menuButton);
+    expect(menuButton).toHaveAttribute("aria-expanded", "true");
+
+    const menuItems = screen.getAllByRole("menuitem");
+    await user.click(menuItems[0]);
+
+    expect(menuButton).toHaveAttribute("aria-expanded", "false");
+    expect(screen.queryByRole("menu")).not.toBeInTheDocument();
+  });
 });

types/OverflowMenu/OverflowMenuItem.svelte.d.ts

@@ -66,6 +66,6 @@ export type OverflowMenuItemProps = Omit<$RestProps, keyof $Props> & $Props;
 
 export default class OverflowMenuItem extends SvelteComponentTyped<
   OverflowMenuItemProps,
-  { click: WindowEventMap["click"]; keydown: WindowEventMap["keydown"] },
+  { click: CustomEvent<MouseEvent>; keydown: WindowEventMap["keydown"] },
   { default: Record<string, never> }
 > {}