@xh/hoist 74.0.0-SNAPSHOT.1749232318711 → 74.0.0-SNAPSHOT.1749665625714

package/core/types/Interfaces.ts

@@ -6,7 +6,8 @@
  */
 
 import {RuleLike} from '@xh/hoist/data';
-import {MouseEvent, ReactElement, ReactNode} from 'react';
+import {MouseEvent, ReactElement, ReactNode, isValidElement} from 'react';
+import {isString} from 'lodash';
 import {LoadSpec} from '../load';
 import {Intent, PlainObject, Thunkable} from './Types';
 
@@ -265,12 +266,41 @@ export interface TrackOptions {
     omit?: Thunkable<boolean>;
 }
 
+/**
+ * The base `MenuToken` type.  '-' is interpreted as the standard textless divider.
+ * Components will likely extend this type to support other strings like 'copyToClipboard',
+ * 'print', etc. which the component then converts into a {@link MenuItem}.
+ */
+export type MenuToken = '-';
+
+/**
+ * `MenuContext` is the set of contextual arguments passed to a {@link MenuItem}'s
+ * `actionFn` and `prepareFn`. `contextMenuEvent` is the right click event that opened the
+ * context menu.  It is optional because the `contextMenu` component can also be used on
+ * popover buttons, where there is no `contextMenuEvent`.
+ *
+ * Components offering a built-in {@link contextMenu} can extend `MenuContext` to add values
+ * relevant to the component.  See for example {@link ChartMenuContext}.
+ */
+export interface MenuContext {
+    contextMenuEvent?: MouseEvent | PointerEvent;
+}
+
+/**
+ * A context menu is specified as an array of items, a function to generate one from a click, or
+ * a full element representing a contextMenu Component.
+ */
+export type ContextMenuSpec<T = MenuToken, C = MenuContext> =
+    | MenuItemLike<T, C>[]
+    | ((e: MouseEvent | PointerEvent, context: C) => MenuItemLike<T, C>[])
+    | boolean;
+
 /**
  *  Basic interface for a MenuItem to appear in a menu.
  *
  *  MenuItems can be displayed within a context menu, or shown when clicking on a button.
  */
-export interface MenuItem {
+export interface MenuItem<T = MenuToken, C = MenuContext> {
     /** Label to be displayed. */
     text: ReactNode;
 
@@ -284,13 +314,13 @@ export interface MenuItem {
     className?: string;
 
     /** Executed when the user clicks the menu item. */
-    actionFn?: (e: MouseEvent | PointerEvent) => void;
+    actionFn?: (e: MouseEvent | PointerEvent, context?: C) => void;
 
     /** Executed before the item is shown.  Use to adjust properties dynamically. */
-    prepareFn?: (me: MenuItem) => void;
+    prepareFn?: (me: MenuItem<T, C>, context?: C) => void;
 
     /** Child menu items. */
-    items?: MenuItemLike[];
+    items?: MenuItemLike<T, C>[];
 
     /** True to disable this item. */
     disabled?: boolean;
@@ -304,12 +334,15 @@ export interface MenuItem {
 
 /**
  * An item that can exist in a Menu.
- *
- * Allows for a ReactNode as divider.  If strings are specified, the implementations may choose
- * an appropriate default display, with '-' providing a standard textless divider that will also
- * be de-duped if appearing at the beginning, or end, or adjacent to another divider at render time.
+ * Components may accept token strings, in addition, '-' will be interpreted as the standard
+ * textless divider that will also be de-duped if appearing at the beginning, or end, or adjacent
+ * to another divider at render time. Also allows for a ReactNode for flexible display.
  */
-export type MenuItemLike = MenuItem | ReactNode;
+export type MenuItemLike<T = MenuToken, C = MenuContext> = MenuItem<T, C> | T | ReactElement;
+
+export function isMenuItem<T, C>(item: MenuItemLike<T, C>): item is MenuItem<T, C> {
+    return !isString(item) && !isValidElement(item);
+}
 
 /**
  * An option to be passed to Select controls

package/desktop/cmp/button/AppMenuButton.ts

@@ -5,7 +5,7 @@
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
 import {MenuItemProps} from '@blueprintjs/core';
-import {hoistCmp, MenuItemLike, MenuItem, XH} from '@xh/hoist/core';
+import {hoistCmp, isMenuItem, MenuItemLike, XH} from '@xh/hoist/core';
 import {ButtonProps, button} from '@xh/hoist/desktop/cmp/button';
 import '@xh/hoist/desktop/register';
 import {Icon} from '@xh/hoist/icon';
@@ -13,8 +13,8 @@ import {menu, menuDivider, menuItem, popover} from '@xh/hoist/kit/blueprint';
 import {wait} from '@xh/hoist/promise';
 import {filterConsecutiveMenuSeparators, isOmitted} from '@xh/hoist/utils/impl';
 import {withDefault} from '@xh/hoist/utils/js';
-import {clone, isEmpty, isString} from 'lodash';
-import {isValidElement, ReactNode} from 'react';
+import {clone, isEmpty} from 'lodash';
+import {ReactNode} from 'react';
 
 export interface AppMenuButtonProps extends ButtonProps {
     /**
@@ -215,7 +215,3 @@ function parseMenuItems(items: MenuItemLike[]): ReactNode[] {
             return menuItem(cfg);
         });
 }
-
-function isMenuItem(item: MenuItemLike): item is MenuItem {
-    return !isString(item) && !isValidElement(item);
-}

package/desktop/cmp/contextmenu/ContextMenu.ts

@@ -4,22 +4,17 @@
  *
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
-import {hoistCmp, HoistProps, MenuItem, MenuItemLike} from '@xh/hoist/core';
+import {hoistCmp, HoistProps, isMenuItem, MenuContext, MenuItemLike} from '@xh/hoist/core';
 import '@xh/hoist/desktop/register';
 import {menu, menuDivider, menuItem} from '@xh/hoist/kit/blueprint';
 import {wait} from '@xh/hoist/promise';
 import {filterConsecutiveMenuSeparators, isOmitted} from '@xh/hoist/utils/impl';
-import {clone, isEmpty, isString} from 'lodash';
-import {isValidElement, ReactElement, ReactNode} from 'react';
-
-/**
- * A context menu is specified as an array of items, a function to generate one from a click, or
- * a full element representing a contextMenu Component.
- */
-export type ContextMenuSpec = MenuItemLike[] | ((e: MouseEvent) => MenuItemLike[]) | ReactElement;
+import {clone, isEmpty} from 'lodash';
+import {ReactNode} from 'react';
 
 export interface ContextMenuProps extends HoistProps {
     menuItems: MenuItemLike[];
+    context?: MenuContext;
 }
 
 /**
@@ -36,8 +31,8 @@ export const [ContextMenu, contextMenu] = hoistCmp.withFactory<ContextMenuProps>
     model: false,
     observer: false,
 
-    render({menuItems}) {
-        const items = parseItems(menuItems);
+    render({menuItems, context}) {
+        const items = parseItems(menuItems, context);
         return isEmpty(items) ? null : menu(items);
     }
 });
@@ -45,13 +40,13 @@ export const [ContextMenu, contextMenu] = hoistCmp.withFactory<ContextMenuProps>
 //---------------------------
 // Implementation
 //---------------------------
-function parseItems(items: MenuItemLike[]): ReactNode[] {
+function parseItems(items: MenuItemLike[], context: MenuContext): ReactNode[] {
     items = items.map(item => {
         if (!isMenuItem(item)) return item;
 
         item = clone(item);
         item.items = clone(item.items);
-        item.prepareFn?.(item);
+        item.prepareFn?.(item, context);
         return item;
     });
 
@@ -64,20 +59,16 @@ function parseItems(items: MenuItemLike[]): ReactNode[] {
             if (!isMenuItem(item)) return item;
 
             // Process items
-            const items = item.items ? parseItems(item.items) : null;
+            const items = item.items ? parseItems(item.items, context) : null;
             return menuItem({
                 text: item.text,
                 icon: item.icon,
                 intent: item.intent,
                 className: item.className,
-                onClick: item.actionFn ? e => wait().then(() => item.actionFn(e)) : null, // do async to allow menu to close
+                onClick: item.actionFn ? e => wait().then(() => item.actionFn(e, context)) : null, // do async to allow menu to close
                 popoverProps: {usePortal: true},
                 disabled: item.disabled,
                 items
             });
         });
 }
-
-function isMenuItem(item: MenuItemLike): item is MenuItem {
-    return !isString(item) && !isValidElement(item);
-}

package/desktop/cmp/dash/canvas/DashCanvas.ts

@@ -129,7 +129,8 @@ const onContextMenu = (e, model) => {
         showContextMenu(
             dashCanvasContextMenu({
                 dashCanvasModel: model,
-                position: {x, y}
+                position: {x, y},
+                contextMenuEvent: e
             }),
             {left: clientX, top: clientY}
         );

package/desktop/cmp/dash/canvas/impl/DashCanvasContextMenu.ts

@@ -5,7 +5,7 @@
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
 
-import {hoistCmp} from '@xh/hoist/core';
+import {hoistCmp, type MenuItemLike} from '@xh/hoist/core';
 import {contextMenu} from '@xh/hoist/desktop/cmp/contextmenu';
 import {createViewMenuItems} from '@xh/hoist/desktop/cmp/dash/canvas/impl/utils';
 import {Icon} from '@xh/hoist/icon';
@@ -21,16 +21,16 @@ import {isEmpty} from 'lodash';
 export const dashCanvasContextMenu = hoistCmp.factory({
     model: null,
     observer: null,
-    render({dashCanvasModel, position}) {
+    render({dashCanvasModel, position, contextMenuEvent}) {
         const menuItems = createMenuItems({dashCanvasModel, position});
-        return contextMenu({menuItems});
+        return contextMenu({menuItems, context: {contextMenuEvent}});
     }
 });
 
 //---------------------------
 // Implementation
 //---------------------------
-function createMenuItems({dashCanvasModel, position}) {
+function createMenuItems({dashCanvasModel, position}): MenuItemLike[] {
     const addMenuItems = createViewMenuItems({dashCanvasModel, position}),
         {extraMenuItems, contentLocked, refreshContextModel} = dashCanvasModel;
     return [

package/desktop/cmp/dash/canvas/impl/utils.ts

@@ -5,6 +5,7 @@
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
 
+import {type MenuItemLike} from '@xh/hoist/core';
 import {Icon} from '@xh/hoist/icon';
 import {DashCanvasModel} from '../DashCanvasModel';
 
@@ -17,7 +18,7 @@ export function createViewMenuItems({
     position = null,
     viewId = null,
     replaceExisting = false
-}) {
+}): MenuItemLike[] {
     if (!dashCanvasModel.ref.current) return [];
 
     const groupedItems = {},

package/desktop/cmp/dash/container/DashContainerModel.ts

@@ -486,7 +486,8 @@ export class DashContainerModel
             stack,
             viewModel,
             index,
-            dashContainerModel: this
+            dashContainerModel: this,
+            contextMenuEvent: e
         });
 
         showContextMenu(menu, offset);

package/desktop/cmp/dash/container/impl/DashContainerContextMenu.ts

@@ -4,7 +4,7 @@
  *
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
-import {hoistCmp} from '@xh/hoist/core';
+import {hoistCmp, type MenuItemLike} from '@xh/hoist/core';
 import {button} from '@xh/hoist/desktop/cmp/button';
 import {contextMenu} from '@xh/hoist/desktop/cmp/contextmenu/ContextMenu';
 import {Icon} from '@xh/hoist/icon';
@@ -23,9 +23,9 @@ import {DashContainerModel} from '../DashContainerModel';
 export const dashContainerContextMenu = hoistCmp.factory({
     model: null,
     observer: null,
-    render(props) {
-        const menuItems = createMenuItems(props);
-        return contextMenu({menuItems});
+    render({contextMenuEvent, ...rest}) {
+        const menuItems = createMenuItems(rest);
+        return contextMenu({menuItems, context: {contextMenuEvent}});
     }
 });
 
@@ -48,7 +48,7 @@ export const dashContainerAddViewButton = hoistCmp.factory<DashContainerModel>({
 //---------------------------
 // Implementation
 //---------------------------
-function createMenuItems(props) {
+function createMenuItems(props): MenuItemLike[] {
     const {dashContainerModel, viewModel} = props,
         {renameLocked} = dashContainerModel,
         ret = [];

package/desktop/cmp/panel/Panel.ts

@@ -15,7 +15,8 @@ import {
     Some,
     TaskObserver,
     useContextModel,
-    uses
+    uses,
+    type ContextMenuSpec
 } from '@xh/hoist/core';
 import {loadingIndicator} from '@xh/hoist/cmp/loadingindicator';
 import {mask} from '@xh/hoist/cmp/mask';
@@ -27,7 +28,6 @@ import {logWarn} from '@xh/hoist/utils/js';
 import {splitLayoutProps} from '@xh/hoist/utils/react';
 import {castArray, omitBy} from 'lodash';
 import {Children, isValidElement, ReactElement, ReactNode, useLayoutEffect, useRef} from 'react';
-import {ContextMenuSpec} from '../contextmenu/ContextMenu';
 import {modalSupport} from '../modalsupport/ModalSupport';
 import {panelHeader} from './impl/PanelHeader';
 import {resizeContainer} from './impl/ResizeContainer';

package/desktop/hooks/UseContextMenu.ts

@@ -4,11 +4,12 @@
  *
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
-import {contextMenu, ContextMenuSpec} from '@xh/hoist/desktop/cmp/contextmenu/ContextMenu';
+import type {ContextMenuSpec} from '@xh/hoist/core';
+import {contextMenu} from '@xh/hoist/desktop/cmp/contextmenu/ContextMenu';
 import {showContextMenu} from '@xh/hoist/kit/blueprint';
 import {logError} from '@xh/hoist/utils/js';
 import {isArray, isEmpty, isFunction, isUndefined} from 'lodash';
-import {cloneElement, isValidElement, ReactElement} from 'react';
+import {cloneElement, isValidElement, MouseEvent, ReactElement} from 'react';
 
 /**
  * Hook to add a right-click context menu to a component.
@@ -21,7 +22,7 @@ import {cloneElement, isValidElement, ReactElement} from 'react';
 export function useContextMenu(child?: ReactElement, spec?: ContextMenuSpec): ReactElement {
     if (!child || isUndefined(spec)) return child;
 
-    const onContextMenu = (e: MouseEvent) => {
+    const onContextMenu = (e: MouseEvent | PointerEvent) => {
         let contextMenuOutput: any = spec;
 
         // 0) Skip if already consumed, otherwise consume (adapted from BP `ContextMenuTarget`).
@@ -34,7 +35,7 @@ export function useContextMenu(child?: ReactElement, spec?: ContextMenuSpec): Re
         }
         if (isArray(contextMenuOutput)) {
             contextMenuOutput = !isEmpty(contextMenuOutput)
-                ? contextMenu({menuItems: contextMenuOutput})
+                ? contextMenu({menuItems: contextMenuOutput, context: {contextMenuEvent: e}})
                 : null;
         }
         if (contextMenuOutput && !isValidElement(contextMenuOutput)) {

package/mobile/cmp/menu/impl/Menu.ts

@@ -5,13 +5,13 @@
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
 import {div, hspacer, vbox} from '@xh/hoist/cmp/layout';
-import {hoistCmp, HoistModel, useLocalModel, MenuItem, MenuItemLike} from '@xh/hoist/core';
+import {hoistCmp, HoistModel, useLocalModel, MenuItemLike, isMenuItem} from '@xh/hoist/core';
 import {listItem} from '@xh/hoist/kit/onsen';
 import {makeObservable, bindable} from '@xh/hoist/mobx';
 import {filterConsecutiveMenuSeparators, isOmitted} from '@xh/hoist/utils/impl';
 import classNames from 'classnames';
-import {clone, isEmpty, isString} from 'lodash';
-import {isValidElement, ReactNode, useEffect} from 'react';
+import {clone, isEmpty} from 'lodash';
+import {ReactNode, useEffect} from 'react';
 
 import './Menu.scss';
 
@@ -107,7 +107,3 @@ class LocalMenuModel extends HoistModel {
             });
     }
 }
-
-function isMenuItem(item: MenuItemLike): item is MenuItem {
-    return !isString(item) && !isValidElement(item);
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xh/hoist",
-  "version": "74.0.0-SNAPSHOT.1749232318711",
+  "version": "74.0.0-SNAPSHOT.1749665625714",
   "description": "Hoist add-on for building and deploying React Applications.",
   "repository": "github:xh/hoist-react",
   "homepage": "https://xh.io",