fix(useContextMenu): api

Author: tenphi

src/components/actions/use-context-menu.docs.mdx

@@ -6,7 +6,7 @@ import { Meta } from '@storybook/blocks';
 
 ## Purpose
 
-`useContextMenu` is a React hook that enables components to display context menus (like `Menu` or `CommandMenu`) at the exact cursor position where the user right-clicked or triggered a context action. Unlike [`useAnchoredMenu`](./use-anchored-menu.docs.mdx) which anchors menus to specific elements, `useContextMenu` positions menus at cursor coordinates, making it perfect for traditional right-click context menus.
+`useContextMenu` is a React hook that enables components to display context menus (like `Menu` or `CommandMenu`) at the exact cursor position where the user right-clicked or triggered a context action. Unlike [`useAnchoredMenu`](./use-anchored-menu.docs.mdx) which anchors menus to specific elements, `useContextMenu` positions menus at cursor coordinates or centers them on the target element, making it perfect for traditional right-click context menus and programmatic menu opening.
 
 The hook automatically handles `onContextMenu` event binding and provides a clean API for both automatic (right-click) and programmatic menu opening.
 
@@ -32,17 +32,17 @@ function useContextMenu<P, T = ComponentProps<typeof MenuTrigger>>(
   targetRef: RefObject<HTMLElement>;
 
   /**
-   * Programmatically opens the menu at the specified event coordinates.
+   * Programmatically opens the menu at the specified coordinates or element center.
    * Runtime props are merged with defaultMenuProps (runtime props take precedence).
    *
-   * @param event - The pointer/mouse event containing coordinates for positioning
    * @param props - Props to pass to the menu component (optional, defaults to defaultMenuProps)
    * @param triggerProps - Additional props for MenuTrigger (merged with defaultTriggerProps)
+   * @param event - The pointer/mouse event containing coordinates for positioning (optional, centers on element if not provided)
    */
   open(
-    event: MouseEvent | PointerEvent | React.MouseEvent | React.PointerEvent,
     props?: P,
     triggerProps?: T,
+    event?: MouseEvent | PointerEvent,
   ): void;
 
   /**
@@ -82,14 +82,20 @@ The hook automatically binds `onContextMenu` events to the `targetRef` element:
 - **`event.preventDefault()`** is called automatically to suppress the browser's native context menu
 - **No manual event binding required** in most cases
 
-### Coordinate-Based Positioning
+### Flexible Positioning
 
-Unlike element-anchored menus, `useContextMenu` positions menus at exact cursor coordinates:
+`useContextMenu` supports two positioning modes:
 
-- Creates an **invisible anchor element** at click coordinates
-- Supports **collision detection** and automatic repositioning
-- **Clamps coordinates** to stay within the container bounds
-- Works with **scrollable containers** by accounting for scroll offset
+1. **Coordinate-Based Positioning** (when event is provided):
+   - Creates an **invisible anchor element** at click coordinates
+   - Supports **collision detection** and automatic repositioning
+   - **Clamps coordinates** to stay within the container bounds
+   - Works with **scrollable containers** by accounting for scroll offset
+
+2. **Center Positioning** (when no event is provided):
+   - Positions the menu at the **center of the target element**
+   - Useful for **programmatic menu opening** from buttons or keyboard shortcuts
+   - Respects **element padding and borders** for accurate centering
 
 ### Props Merging Strategy
 
@@ -148,31 +154,38 @@ function FileItem({ file }) {
 
 | Feature | `useContextMenu` | `useAnchoredMenu` |
 |---------|------------------|-------------------|
-| **Positioning** | Cursor coordinates | Element-anchored |
-| **Trigger** | Right-click (automatic) | Manual (button click) |
+| **Positioning** | Cursor coordinates or element center | Element-anchored |
+| **Trigger** | Right-click (automatic) + programmatic | Manual (button click) |
 | **Event Binding** | Automatic `onContextMenu` | Manual event handling |
-| **Use Cases** | Context menus, right-click actions | Dropdown menus, action buttons |
+| **Use Cases** | Context menus, right-click actions, toolbar dropdowns | Dropdown menus, action buttons |
 | **Default Placement** | `"bottom start"` | `"bottom start"` |
 | **Setup Complexity** | Minimal (auto-binding) | Manual event handling |
 
 ## Implementation Notes
 
 ### Coordinate Calculation
 
-The hook calculates menu position by:
+The hook calculates menu position differently based on whether an event is provided:
 
+**With Event (Coordinate-Based):**
 1. **Getting viewport coordinates** from the pointer event
 2. **Converting to container-relative coordinates** accounting for borders and scroll
 3. **Clamping to container bounds** to ensure the menu stays visible
 4. **Creating an invisible anchor** at the calculated position
 5. **Delegating to MenuTrigger** for collision detection and final positioning
 
+**Without Event (Center-Based):**
+1. **Calculating element center** using `clientWidth/2` and `clientHeight/2`
+2. **Accounting for scroll offset** to position relative to content area
+3. **Clamping to container bounds** to ensure proper positioning
+4. **Creating an invisible anchor** at the center position
+
 ### Event Handling
 
 - **Automatic binding** occurs via `useEffect` on the `targetRef`
 - **Event listeners** are properly cleaned up on unmount
 - **`preventDefault()`** is called automatically for context menu events
-- **Manual `open()` calls** can still prevent default if needed
+- **Manual `open()` calls** can still prevent default if an event is provided
 
 ### Memory Management
 

src/components/actions/use-context-menu.test.tsx

@@ -79,14 +79,17 @@ describe('useContextMenu', () => {
     );
 
     return (
-      <div ref={targetRef} data-qa="container">
+      <div
+        ref={targetRef as React.RefObject<HTMLDivElement>}
+        data-qa="container"
+      >
         <button
           data-qa="trigger"
           onClick={(e) => {
             if (onTriggerClick) {
               onTriggerClick();
             }
-            open(e, componentProps, triggerProps);
+            open(componentProps, triggerProps, e);
           }}
         >
           Open Menu
@@ -435,11 +438,11 @@ describe('useContextMenu', () => {
         useContextMenu<HTMLDivElement>(TestMenuComponent);
 
       const handleClick1 = (e: React.MouseEvent) => {
-        open(e, { onAction: onAction1, sadf: '123' });
+        open({ onAction: onAction1, sadf: '123' }, undefined, e);
       };
 
       const handleClick2 = (e: React.MouseEvent) => {
-        open(e, { onAction: onAction2 });
+        open({ onAction: onAction2 }, undefined, e);
       };
 
       return (
@@ -597,7 +600,7 @@ describe('useContextMenu', () => {
     } as any;
 
     expect(() => {
-      result.current.open(mockEvent, {});
+      result.current.open({}, undefined, mockEvent);
     }).toThrow(
       'useContextMenu: MenuTrigger must be rendered. Use `rendered` property to include it in your component tree.',
     );
@@ -680,7 +683,7 @@ describe('useContextMenu', () => {
 
       return (
         <div ref={targetRef} data-qa="container">
-          <button data-qa="trigger" onClick={(e) => open(e, {})}>
+          <button data-qa="trigger" onClick={(e) => open({}, undefined, e)}>
             {isOpen ? 'Close Menu' : 'Open Menu'}
           </button>
           <button data-qa="close-button" onClick={close}>
@@ -835,7 +838,7 @@ describe('useContextMenu', () => {
       );
 
       const handleManualOpen = (e: React.MouseEvent) => {
-        open(e, { onAction: runtimeAction, width: '200px' }); // Should override default onAction
+        open({ onAction: runtimeAction, width: '200px' }, undefined, e); // Should override default onAction
       };
 
       return (
@@ -883,4 +886,66 @@ describe('useContextMenu', () => {
     // Should use default action
     expect(defaultAction).toHaveBeenCalledWith('edit');
   });
+
+  it('should position menu at element center when no event is provided', async () => {
+    const onAction = jest.fn();
+
+    const TestCenterWrapper = () => {
+      const { targetRef, open, rendered } = useContextMenu<HTMLDivElement>(
+        TestMenuComponent,
+        { placement: 'bottom start' },
+        { onAction },
+      );
+
+      const handleCenterOpen = () => {
+        open(); // No event provided - should center on element
+      };
+
+      return (
+        <div
+          ref={targetRef}
+          data-qa="container"
+          style={{ width: 200, height: 100, padding: '20px' }}
+        >
+          <button data-qa="center-trigger" onClick={handleCenterOpen}>
+            Open Centered
+          </button>
+          {rendered}
+        </div>
+      );
+    };
+
+    const { getByTestId, getByRole, getByText } = renderWithRoot(
+      <TestCenterWrapper />,
+    );
+
+    const centerTrigger = getByTestId('center-trigger');
+
+    // Open without event (should center on element)
+    await act(async () => {
+      await userEvent.click(centerTrigger);
+    });
+
+    // Menu should be visible
+    await waitFor(() => {
+      expect(getByRole('menu')).toBeInTheDocument();
+    });
+
+    expect(getByText('Edit')).toBeInTheDocument();
+
+    // Verify that invisible anchor is positioned (we can't easily verify exact center coordinates in tests)
+    const container = getByTestId('container');
+    const invisibleAnchor = container.querySelector(
+      'span[style*="position: absolute"]',
+    );
+    expect(invisibleAnchor).toBeInTheDocument();
+
+    // Click on an item to test action
+    const editItem = getByText('Edit');
+    await act(async () => {
+      await userEvent.click(editItem);
+    });
+
+    expect(onAction).toHaveBeenCalledWith('edit');
+  });
 });

src/components/actions/use-context-menu.tsx

@@ -32,17 +32,17 @@ export interface UseContextMenuReturn<
   targetRef: RefObject<E>;
 
   /**
-   * Programmatically opens the menu at the specified event coordinates.
+   * Programmatically opens the menu at the specified coordinates or element center.
    * Runtime props are merged with defaultMenuProps (runtime props take precedence).
    *
-   * @param event - The pointer/mouse event containing coordinates for positioning
    * @param props - Props to pass to the menu component (optional, defaults to defaultMenuProps)
    * @param triggerProps - Additional props for MenuTrigger (merged with defaultTriggerProps)
+   * @param event - The pointer/mouse event containing coordinates for positioning (optional, centers on element if not provided)
    */
   open(
-    event: NativeMouseEvent | NativePointerEvent | MouseEvent | PointerEvent,
     props?: P,
     triggerProps?: T,
+    event?: NativeMouseEvent | NativePointerEvent | MouseEvent | PointerEvent,
   ): void;
 
   /**
@@ -134,10 +134,35 @@ export function useContextMenu<
   // element's scroll offset into account. Without the scroll offset the menu
   // would be rendered at the wrong place inside scrollable containers.
   const calculatePosition = (
-    event: NativeMouseEvent | NativePointerEvent | MouseEvent | PointerEvent,
+    event?: NativeMouseEvent | NativePointerEvent | MouseEvent | PointerEvent,
   ) => {
     const container = targetRef.current;
 
+    // If no event is provided, position at the center of the element
+    if (!event) {
+      if (!container) {
+        return { x: 0, y: 0 };
+      }
+
+      const containerRect = container.getBoundingClientRect();
+      const scrollLeft = container.scrollLeft;
+      const scrollTop = container.scrollTop;
+
+      const computed = window.getComputedStyle(container);
+      const borderLeft = parseFloat(computed.borderLeftWidth) || 0;
+      const borderTop = parseFloat(computed.borderTopWidth) || 0;
+
+      // Position at the center of the element's content area
+      const x = container.clientWidth / 2 + scrollLeft;
+      const y = container.clientHeight / 2 + scrollTop;
+
+      // Clamp to the full scroll size
+      const clampedX = Math.max(0, Math.min(x, container.scrollWidth));
+      const clampedY = Math.max(0, Math.min(y, container.scrollHeight));
+
+      return { x: clampedX, y: clampedY };
+    }
+
     // If the target reference is missing, fall back to viewport coordinates.
     if (!container) {
       const { clientX = 0, clientY = 0 } = event;
@@ -171,12 +196,12 @@ export function useContextMenu<
     return { x: clampedX, y: clampedY };
   };
 
-  // 'open' accepts an event for positioning, props required by the Component and opens the menu
+  // 'open' accepts props, trigger props, and optional event for positioning, then opens the menu
   const open = useEvent(
     (
-      event: NativeMouseEvent | NativePointerEvent | MouseEvent | PointerEvent,
       props?: P,
       triggerProps?: T,
+      event?: NativeMouseEvent | NativePointerEvent | MouseEvent | PointerEvent,
     ) => {
       setupCheck();
 
@@ -194,6 +219,7 @@ export function useContextMenu<
 
       // Prevent default context menu if it's a context menu event
       if (
+        event &&
         'preventDefault' in event &&
         typeof event.preventDefault === 'function'
       ) {
@@ -239,7 +265,7 @@ export function useContextMenu<
         const pos = calculatePosition(event);
         setAnchorPosition(pos);
       } else {
-        open(event, defaultMenuProps);
+        open(defaultMenuProps, undefined, event);
       }
     },
   );