@xh/hoist 75.0.0-SNAPSHOT.1749666833237 → 75.0.0-SNAPSHOT.1750966316712

package/CHANGELOG.md

@@ -2,23 +2,32 @@
 
 ## v75.0.0-SNAPSHOT - unreleased
 
+### 🎁 New Features
+
+* Added props to `ViewManager` to customize icons used for different types of views, and modified
+  default icons for Global and Shared views.
+* Added `ViewManager.extraMenuItems` prop to allow insertion of custom, app-specific items into the
+  component's standard menu.
+
 ## v74.0.0 - 2025-06-11
 
 ### 💥 Breaking Changes (upgrade difficulty: 🟢 LOW - minor changes to ViewManagerModel, ChartModel)
 
 * Removed `ViewManagerModel.settleTime`. Now set via individual `PersistOptions.settleTime` instead.
-* ️Removed `ChartModel.showContextMenu`.  Use a setting of `false` for the new `ChartModel.contextMenu`
-property instead.
+* ️Removed `ChartModel.showContextMenu`. Use a setting of `false` for the new
+  `ChartModel.contextMenu` property instead.
 
 ### 🎁 New Features
+
 * Added `ViewManagerModel.preserveUnsavedChanges` flag to opt-out of that behaviour.
 * Added `PersistOptions.settleTime` to configure time to wait for state to settle before persisting.
 * Support for grid column level `onCellClicked` events.
 * General improvements to `MenuItem` api
-  * New `MenuContext` object now sent as 2nd arg to `actionFn` and `prepareFn`.
-  * New `ChartModel.contextMenu` property provides a fully customizable context menu for charts.
+    * New `MenuContext` object now sent as 2nd arg to `actionFn` and `prepareFn`.
+    * New `ChartModel.contextMenu` property provides a fully customizable context menu for charts.
 
 ### 🐞 Bug Fixes
+
 * Improved `ViewManagerModel.settleTime` by delegating to individual `PersistenceProviders`.
 * Fixed bug where grid column state could become unintentionally dirty when columns were hidden.
 * Improved `WebsocketService` heartbeat detection to auto-reconnect when the socket reports as open

package/build/types/cmp/viewmanager/ViewInfo.d.ts

@@ -15,15 +15,19 @@ export declare class ViewInfo {
     readonly description: string;
     /** User owning this view. Null if the view is global.*/
     readonly owner: string;
-    /** Is the owner making this view accessible to others? Always true for global views. */
+    /**
+     * True if the owner (which can be the current user) has made this view accessible to all other
+     * users. Note always `false` for global views, to better distinguish the two sharing models.
+     */
     readonly isShared: boolean;
     /** True if this view is global and visible to all users. */
     readonly isGlobal: boolean;
     /** Optional group name used for bucketing this view in display. */
     readonly group: string;
     /**
-     * Should this view be pinned by users by default?
-     * This value is intended to be used for global views only.
+     * True if this view should be pinned by default to all users' menus, where it will appear
+     * unless the user has explicitly unpinned it. Only applicable for global views, can be enabled
+     * by view managers to promote especially important global views and ensure users see them.
      */
     readonly isDefaultPinned: boolean;
     /**

package/build/types/desktop/cmp/viewmanager/ViewManager.d.ts

@@ -1,26 +1,42 @@
-import { HoistProps } from '@xh/hoist/core';
+import { HoistProps, MenuItemLike } from '@xh/hoist/core';
 import { ViewManagerModel } from '@xh/hoist/cmp/viewmanager';
 import { ButtonProps } from '@xh/hoist/desktop/cmp/button';
+import { ReactElement } from 'react';
 import './ViewManager.scss';
-/**
- * Visibility options for save/revert button.
- *
- * 'never' to hide button.
- * 'whenDirty' to only show when persistence state is dirty and button is therefore enabled.
- * 'always' will always show button.
- */
-export type ViewManagerStateButtonMode = 'whenDirty' | 'always' | 'never';
 export interface ViewManagerProps extends HoistProps<ViewManagerModel> {
     menuButtonProps?: Partial<ButtonProps>;
     saveButtonProps?: Partial<ButtonProps>;
     revertButtonProps?: Partial<ButtonProps>;
+    /** Button icon when on the default (in-code state) view. Default `Icon.bookmark`. */
+    defaultViewIcon?: ReactElement;
+    /** Button icon when the selected view is owned by the current user. Default `Icon.bookmark`. */
+    ownedViewIcon?: ReactElement;
+    /** Button icon when the selected view is shared by another user. Default `Icon.users`. */
+    sharedViewIcon?: ReactElement;
+    /** Button icon when the selected view is globally shared. Default `Icon.globe`. */
+    globalViewIcon?: ReactElement;
     /** Default 'whenDirty' */
     showSaveButton?: ViewManagerStateButtonMode;
     /** Default 'never' */
     showRevertButton?: ViewManagerStateButtonMode;
-    /** Side the save and revert buttons should appear on (default 'right') */
+    /** Side relative to the menu on which save/revert buttons should render. Default 'right'. */
     buttonSide?: 'left' | 'right';
+    /**
+     * Array of extra menu items. Can contain:
+     *  + `MenuItems` or configs to create them.
+     *  + `MenuDividers` or the special string token '-'.
+     *  + React Elements or strings, which will be interpreted as the `text` property for a MenuItem.
+     */
+    extraMenuItems?: MenuItemLike[];
 }
+/**
+ * Visibility options for save/revert buttons inlined next to the ViewManager menu:
+ *      'never' to always hide - user must save/revert via menu.
+ *      'whenDirty' (default) to show only when view state is dirty and the button is enabled.
+ *      'always' to always show, including when view not dirty and the button is disabled.
+ *          Useful to avoid jumpiness in toolbar layouts.
+ */
+export type ViewManagerStateButtonMode = 'whenDirty' | 'always' | 'never';
 /**
  * Desktop ViewManager component - a button-based menu for saving and swapping between named
  * bundles of persisted component state (e.g. grid views, dashboards, and similar).

package/build/types/utils/impl/MenuItems.d.ts

@@ -0,0 +1,13 @@
+import { MenuItemLike } from '@xh/hoist/core';
+import { ReactNode } from 'react';
+/**
+ * Parse MenuItem configs into Blueprint MenuItems.
+ *
+ * Note this is currently used in a few limited places and is not generally applied to all menu-
+ * like components in Hoist. In particular, it is not used by the `menu` component re-exported from
+ * Blueprint. See https://github.com/xh/hoist-react/issues/2400 covering TBD work to more fully
+ * standardize a Hoist menu component that might then incorporate this processing.
+ *
+ * @internal
+ */
+export declare function parseMenuItems(items: MenuItemLike[]): ReactNode[];

package/build/types/utils/impl/index.d.ts

@@ -2,3 +2,4 @@ export * from './Separators';
 export * from './TimeZone';
 export * from './Equals';
 export * from './IsOmitted';
+export * from './MenuItems';

package/cmp/viewmanager/ViewInfo.ts

@@ -29,7 +29,10 @@ export class ViewInfo {
     /** User owning this view. Null if the view is global.*/
     readonly owner: string;
 
-    /** Is the owner making this view accessible to others? Always true for global views. */
+    /**
+     * True if the owner (which can be the current user) has made this view accessible to all other
+     * users. Note always `false` for global views, to better distinguish the two sharing models.
+     */
     readonly isShared: boolean;
 
     /** True if this view is global and visible to all users. */
@@ -39,8 +42,9 @@ export class ViewInfo {
     readonly group: string;
 
     /**
-     * Should this view be pinned by users by default?
-     * This value is intended to be used for global views only.
+     * True if this view should be pinned by default to all users' menus, where it will appear
+     * unless the user has explicitly unpinned it. Only applicable for global views, can be enabled
+     * by view managers to promote especially important global views and ensure users see them.
      */
     readonly isDefaultPinned: boolean;
 

package/desktop/cmp/button/AppMenuButton.ts

@@ -4,17 +4,13 @@
  *
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
-import {MenuItemProps} from '@blueprintjs/core';
-import {hoistCmp, isMenuItem, MenuItemLike, XH} from '@xh/hoist/core';
+import {hoistCmp, 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';
-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 {menu, popover} from '@xh/hoist/kit/blueprint';
+import {parseMenuItems} from '@xh/hoist/utils/impl';
 import {withDefault} from '@xh/hoist/utils/js';
-import {clone, isEmpty} from 'lodash';
-import {ReactNode} from 'react';
 
 export interface AppMenuButtonProps extends ButtonProps {
     /**
@@ -176,42 +172,3 @@ function buildMenuItems(props: AppMenuButtonProps) {
 
     return parseMenuItems([...extraItems, '-', ...defaultItems]);
 }
-
-function parseMenuItems(items: MenuItemLike[]): ReactNode[] {
-    items = items.map(item => {
-        if (!isMenuItem(item)) return item;
-
-        item = clone(item);
-        item.items = clone(item.items);
-        item.prepareFn?.(item);
-        return item;
-    });
-
-    return items
-        .filter(it => !isMenuItem(it) || (!it.hidden && !isOmitted(it)))
-        .filter(filterConsecutiveMenuSeparators())
-        .map(item => {
-            if (item === '-') return menuDivider();
-            if (!isMenuItem(item)) return item;
-
-            const {actionFn} = item;
-
-            // Create menuItem from config
-            const cfg: MenuItemProps = {
-                text: item.text,
-                icon: item.icon,
-                intent: item.intent,
-                className: item.className,
-                onClick: actionFn ? e => wait().then(() => actionFn(e)) : null, // do async to allow menu to close
-                disabled: item.disabled
-            };
-
-            // Recursively parse any submenus
-            if (!isEmpty(item.items)) {
-                cfg.children = parseMenuItems(item.items);
-                cfg.popoverProps = {openOnTargetFocus: false};
-            }
-
-            return menuItem(cfg);
-        });
-}

package/desktop/cmp/viewmanager/ViewManager.ts

@@ -7,13 +7,14 @@
 
 import {box, fragment, hbox} from '@xh/hoist/cmp/layout';
 import {spinner} from '@xh/hoist/cmp/spinner';
-import {hoistCmp, HoistProps, useLocalModel, uses} from '@xh/hoist/core';
+import {hoistCmp, HoistProps, MenuItemLike, useLocalModel, uses} from '@xh/hoist/core';
 import {ViewManagerModel} from '@xh/hoist/cmp/viewmanager';
 import {button, ButtonProps} from '@xh/hoist/desktop/cmp/button';
 import {Icon} from '@xh/hoist/icon';
 import {popover} from '@xh/hoist/kit/blueprint';
 import {useOnVisibleChange} from '@xh/hoist/utils/react';
 import {startCase} from 'lodash';
+import {ReactElement} from 'react';
 import {viewMenu} from './ViewMenu';
 import {ViewManagerLocalModel} from './ViewManagerLocalModel';
 import {manageDialog} from './dialog/ManageDialog';
@@ -21,28 +22,44 @@ import {saveAsDialog} from './dialog/SaveAsDialog';
 
 import './ViewManager.scss';
 
-/**
- * Visibility options for save/revert button.
- *
- * 'never' to hide button.
- * 'whenDirty' to only show when persistence state is dirty and button is therefore enabled.
- * 'always' will always show button.
- */
-export type ViewManagerStateButtonMode = 'whenDirty' | 'always' | 'never';
-
 export interface ViewManagerProps extends HoistProps<ViewManagerModel> {
     menuButtonProps?: Partial<ButtonProps>;
     saveButtonProps?: Partial<ButtonProps>;
     revertButtonProps?: Partial<ButtonProps>;
 
+    /** Button icon when on the default (in-code state) view. Default `Icon.bookmark`. */
+    defaultViewIcon?: ReactElement;
+    /** Button icon when the selected view is owned by the current user. Default `Icon.bookmark`. */
+    ownedViewIcon?: ReactElement;
+    /** Button icon when the selected view is shared by another user. Default `Icon.users`. */
+    sharedViewIcon?: ReactElement;
+    /** Button icon when the selected view is globally shared. Default `Icon.globe`. */
+    globalViewIcon?: ReactElement;
+
     /** Default 'whenDirty' */
     showSaveButton?: ViewManagerStateButtonMode;
     /** Default 'never' */
     showRevertButton?: ViewManagerStateButtonMode;
-    /** Side the save and revert buttons should appear on (default 'right') */
+    /** Side relative to the menu on which save/revert buttons should render. Default 'right'. */
     buttonSide?: 'left' | 'right';
+    /**
+     * Array of extra menu items. Can contain:
+     *  + `MenuItems` or configs to create them.
+     *  + `MenuDividers` or the special string token '-'.
+     *  + React Elements or strings, which will be interpreted as the `text` property for a MenuItem.
+     */
+    extraMenuItems?: MenuItemLike[];
 }
 
+/**
+ * Visibility options for save/revert buttons inlined next to the ViewManager menu:
+ *      'never' to always hide - user must save/revert via menu.
+ *      'whenDirty' (default) to show only when view state is dirty and the button is enabled.
+ *      'always' to always show, including when view not dirty and the button is disabled.
+ *          Useful to avoid jumpiness in toolbar layouts.
+ */
+export type ViewManagerStateButtonMode = 'whenDirty' | 'always' | 'never';
+
 /**
  * Desktop ViewManager component - a button-based menu for saving and swapping between named
  * bundles of persisted component state (e.g. grid views, dashboards, and similar).
@@ -60,9 +77,14 @@ export const [ViewManager, viewManager] = hoistCmp.withFactory<ViewManagerProps>
         menuButtonProps,
         saveButtonProps,
         revertButtonProps,
+        defaultViewIcon = Icon.bookmark(),
+        ownedViewIcon = Icon.bookmark(),
+        sharedViewIcon = Icon.users(),
+        globalViewIcon = Icon.globe(),
         showSaveButton = 'whenDirty',
         showRevertButton = 'never',
-        buttonSide = 'right'
+        buttonSide = 'right',
+        extraMenuItems = []
     }: ViewManagerProps) {
         const {loadModel} = model,
             locModel = useLocalModel(() => new ViewManagerLocalModel(model)),
@@ -70,7 +92,17 @@ export const [ViewManager, viewManager] = hoistCmp.withFactory<ViewManagerProps>
             revert = revertButton({model: locModel, mode: showRevertButton, ...revertButtonProps}),
             menu = popover({
                 disabled: !locModel.isVisible, // Prevent orphaned popover menu
-                item: menuButton({model: locModel, ...menuButtonProps}),
+                item: menuButton({
+                    model: locModel,
+                    icon: buttonIcon({
+                        model: locModel,
+                        defaultViewIcon,
+                        ownedViewIcon,
+                        sharedViewIcon,
+                        globalViewIcon
+                    }),
+                    ...menuButtonProps
+                }),
                 content: loadModel.isPending
                     ? box({
                           item: spinner({compact: true}),
@@ -79,7 +111,7 @@ export const [ViewManager, viewManager] = hoistCmp.withFactory<ViewManagerProps>
                           height: 30,
                           width: 30
                       })
-                    : viewMenu({model: locModel}),
+                    : viewMenu({model: locModel, extraMenuItems}),
                 onOpening: () => model.refreshAsync(),
                 placement: 'bottom',
                 popoverClassName: 'xh-view-manager__popover'
@@ -97,13 +129,13 @@ export const [ViewManager, viewManager] = hoistCmp.withFactory<ViewManagerProps>
 });
 
 const menuButton = hoistCmp.factory<ViewManagerLocalModel>({
-    render({model, ...rest}) {
+    render({model, icon, ...rest}) {
         const {view, typeDisplayName, isLoading} = model.parent;
         return button({
             className: 'xh-view-manager__menu-button',
             text: view.isDefault ? `Default ${startCase(typeDisplayName)}` : view.name,
             icon: !isLoading
-                ? Icon.bookmark()
+                ? icon
                 : box({
                       item: spinner({width: 13, height: 13, style: {margin: 'auto'}}),
                       width: 16.25
@@ -115,6 +147,16 @@ const menuButton = hoistCmp.factory<ViewManagerLocalModel>({
     }
 });
 
+const buttonIcon = hoistCmp.factory<ViewManagerLocalModel>({
+    render({model, ownedViewIcon, sharedViewIcon, globalViewIcon, defaultViewIcon}) {
+        const {view} = model.parent;
+        if (view.isOwned) return ownedViewIcon;
+        if (view.isShared) return sharedViewIcon;
+        if (view.isGlobal) return globalViewIcon;
+        return defaultViewIcon;
+    }
+});
+
 const saveButton = hoistCmp.factory<ViewManagerLocalModel>({
     render({model, mode, ...rest}) {
         if (hideStateButton(model, mode)) return null;

package/desktop/cmp/viewmanager/ViewMenu.ts

@@ -11,6 +11,7 @@ import {switchInput} from '@xh/hoist/desktop/cmp/input';
 import {Icon} from '@xh/hoist/icon';
 import {menu, menuDivider, menuItem} from '@xh/hoist/kit/blueprint';
 import {pluralize} from '@xh/hoist/utils/js';
+import {filterConsecutiveMenuSeparators, parseMenuItems} from '@xh/hoist/utils/impl';
 import {Dictionary} from 'express-serve-static-core';
 import {each, filter, groupBy, isEmpty, isFunction, orderBy, some, startCase} from 'lodash';
 import {ReactNode} from 'react';
@@ -20,10 +21,16 @@ import {ViewManagerLocalModel} from './ViewManagerLocalModel';
  * Default Menu used by ViewManager.
  */
 export const viewMenu = hoistCmp.factory<ViewManagerLocalModel>({
-    render({model}) {
+    render({model, extraMenuItems}) {
         return menu({
             className: 'xh-view-manager__menu',
-            items: [...getNavMenuItems(model.parent), menuDivider(), ...getOtherMenuItems(model)]
+            items: [
+                ...getNavMenuItems(model.parent),
+                menuDivider(),
+                ...parseMenuItems(extraMenuItems),
+                menuDivider(),
+                ...getOtherMenuItems(model)
+            ].filter(filterConsecutiveMenuSeparators())
         });
     }
 });

package/package.json

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