@xh/hoist 74.0.0-SNAPSHOT.1749050851202 → 74.0.0-SNAPSHOT.1749597895949

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/filter/FilterChooser.ts

@@ -17,7 +17,7 @@ import {splitLayoutProps} from '@xh/hoist/utils/react';
 import classNames from 'classnames';
 import {isEmpty, sortBy} from 'lodash';
 import {badge} from '@xh/hoist/cmp/badge';
-import {ReactElement} from 'react';
+import {cloneElement, ReactElement} from 'react';
 import './FilterChooser.scss';
 
 export interface FilterChooserProps extends HoistProps<FilterChooserModel>, LayoutProps {
@@ -39,6 +39,8 @@ export interface FilterChooserProps extends HoistProps<FilterChooserModel>, Layo
     menuWidth?: number;
     /** Text to display when control is empty. */
     placeholder?: string;
+    /** Icon clicked to launch favorites menu. (Defaults to Icon.favorite()) */
+    favoritesIcon?: ReactElement;
 }
 
 /**
@@ -65,7 +67,8 @@ export const [FilterChooser, filterChooser] = hoistCmp.withFactory<FilterChooser
                 leftIcon,
                 maxMenuHeight,
                 menuPlacement,
-                menuWidth
+                menuWidth,
+                favoritesIcon
             } = chooserProps,
             disabled = unsupportedFilter || chooserProps.disabled,
             placeholder = unsupportedFilter
@@ -115,7 +118,7 @@ export const [FilterChooser, filterChooser] = hoistCmp.withFactory<FilterChooser
                                 })
                             },
                             components: {
-                                DropdownIndicator: () => favoritesIcon(model)
+                                DropdownIndicator: () => favoritesIconCmp(model, favoritesIcon)
                             }
                         }
                     })
@@ -210,15 +213,18 @@ const messageOption = hoistCmp.factory({
 //-----------------
 // Favorites
 //------------------
-function favoritesIcon(model) {
+function favoritesIconCmp(model, favoritesIcon) {
     if (!model.persistFavorites) return null;
-    return Icon.favorite({
+
+    const iconProps = {
         className: classNames('xh-select__indicator', 'xh-filter-chooser-favorite-icon'),
         onMouseDown: e => {
             model.openFavoritesMenu();
             e.stopPropagation();
         }
-    });
+    };
+
+    return favoritesIcon ? cloneElement(favoritesIcon, iconProps) : Icon.favorite(iconProps);
 }
 
 const favoritesMenu = hoistCmp.factory<FilterChooserModel>({

package/desktop/cmp/grouping/GroupingChooser.ts

@@ -16,6 +16,7 @@ import {menu, menuDivider, menuItem, popover} from '@xh/hoist/kit/blueprint';
 import {dragDropContext, draggable, droppable} from '@xh/hoist/kit/react-beautiful-dnd';
 import {elemWithin, getTestId, TEST_ID} from '@xh/hoist/utils/js';
 import {splitLayoutProps} from '@xh/hoist/utils/react';
+import {ReactElement} from 'react';
 import classNames from 'classnames';
 import {compact, isEmpty, sortBy} from 'lodash';
 import './GroupingChooser.scss';
@@ -38,6 +39,9 @@ export interface GroupingChooserProps extends ButtonProps<GroupingChooserModel>
 
     /** True (default) to style target button as an input field - blends better in toolbars. */
     styleButtonAsInput?: boolean;
+
+    /** Icon clicked to launch favorites menu. Defaults to Icon.favorite() */
+    favoritesIcon?: ReactElement;
 }
 
 /**
@@ -62,6 +66,7 @@ export const [GroupingChooser, groupingChooser] = hoistCmp.withFactory<GroupingC
             popoverPosition = 'bottom',
             styleButtonAsInput = true,
             testId,
+            favoritesIcon,
             ...rest
         },
         ref
@@ -101,7 +106,7 @@ export const [GroupingChooser, groupingChooser] = hoistCmp.withFactory<GroupingC
                         onClick: () => model.toggleEditor(),
                         testId
                     }),
-                    favoritesIcon({testId: favoritesIconTestId})
+                    favoritesIconCmp({testId: favoritesIconTestId, favoritesIcon})
                 ),
                 content: favoritesIsOpen
                     ? favoritesMenu({testId: favoritesMenuTestId})
@@ -315,11 +320,11 @@ function getDimOptions(dims, model) {
 //------------------
 // Favorites
 //------------------
-const favoritesIcon = hoistCmp.factory<GroupingChooserModel>({
-    render({model, testId}) {
+const favoritesIconCmp = hoistCmp.factory<GroupingChooserModel>({
+    render({model, testId, favoritesIcon}) {
         if (!model.persistFavorites) return null;
         return div({
-            item: Icon.favorite(),
+            item: favoritesIcon ?? Icon.favorite(),
             className: 'xh-grouping-chooser__favorite-icon',
             [TEST_ID]: testId,
             onClick: e => {

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.1749050851202",
+  "version": "74.0.0-SNAPSHOT.1749597895949",
   "description": "Hoist add-on for building and deploying React Applications.",
   "repository": "github:xh/hoist-react",
   "homepage": "https://xh.io",