@xh/hoist 75.0.0-SNAPSHOT.1753487024547 → 75.0.0-SNAPSHOT.1753720955374

package/CHANGELOG.md

@@ -21,6 +21,8 @@
 * Deprecated the `RelativeTimestamp.options` prop - all the same options are now top-level props.
 * Added new `GroupingChooserModel.sortDimensions` config. Set to `false` to respect the order in
   which `dimensions` are provided to the model.
+* Added new `ClipboardButton.errorMessage` prop to customize or suppress a toast alert if the copy
+  operation fails. Set to `false` to fail silently (the behavior prior to this change).
 
 ### 🐞 Bug Fixes
 

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

@@ -25,68 +25,81 @@ export interface ViewUserState {
 }
 export interface ViewManagerConfig {
     /**
-     * True (default) to allow user to opt in to automatically saving changes to their current view.
+     * Required discriminator for the particular class of views to be loaded and managed by this
+     * model. Used to set the `type` property on all JSONBlobs persisted by this model.
+     *
+     * Choose something descriptive and specific enough to be identifiable and allow for different
+     * ViewManagers to be added to your app in the future - e.g. `portfolioGridView` or
+     * `tradeBlotterDashboard`.
+     */
+    type: string;
+    /**
+     * Optional user-facing qualifier (default "default") for the special in-code default view
+     * option, if enabled. Will be prepended to `typeDisplayName`.
+     *
+     * A use case is to support a ViewManager persisted Dashboard, where the in-code default is an
+     * empty layout, this config is set to "New", and the `typeDisplayName` is set to "Dashboard".
+     * This results in a "New Dashboard" option in the menu, allowing users to quickly access a
+     * blank dashboard to start building from scratch, while forcing a save-as to persist.
      */
+    defaultDisplayName?: string;
+    /** True (default) to allow users to opt-in to auto-saving changes to their current view. */
     enableAutoSave?: boolean;
     /**
-     * True (default) to allow the user to select a "Default" option that restores all persisted
-     * objects to their in-code defaults. If not enabled, at least one saved view should be created
-     * in advance, so that there is a clear initial selection for users without any private views.
+     * True (default) to allow the user to select a special view from the menu that restores all
+     * persisted objects to their in-code defaults. If not enabled, at least one globally shared
+     * view should be added to provide an initial selection for users without any private views.
      */
     enableDefault?: boolean;
     /**
      * True (default) to enable "global" views - i.e. views that are not owned by a user and are
-     * available to all.
+     * available to all. At least some users should have `manageGlobal` set to true to allow
+     * creation and management of these views.
      */
     enableGlobal?: boolean;
-    /**
-     * True (default) to allow users to share their views with other users.
-     */
+    /** True (default) to allow users to share their views with other users. */
     enableSharing?: boolean;
     /**
-     * True (default) to save pending state to SessionStorage so that it can be restored across
-     * browser refreshes. Unlike auto-save, this does not write to the database.
+     * User-facing qualifier for labelling globally shared views - default "global". A use case
+     * would be to set to the name of the company/team that manages these canonical views, e.g.
+     * "Acme Corp".
      */
-    preserveUnsavedChanges?: boolean;
+    globalDisplayName?: string;
     /**
-     * Function to determine the initial view for a user, when no view has already been persisted.
-     * Will be passed a list of views available to the current user.  Implementations where
-     * enableDefault is set false should typically return some view, if any views are
-     * available.  If no view is returned, the control will be forced to fall back on the default.
+     * Function to determine the initial view for a user, when they have no prior view already
+     * persisted. Called with a list of views available to the current user.
      *
-     * Must be set when enableDefault is false.
+     * Must be set when `enableDefault: false`. Developers should take care to return *some* view
+     * in this case, if any are available. If no view is returned, the control will be forced to
+     * fall back to the in-code default.
      */
     initialViewSpec?: (views: ViewInfo[]) => ViewInfo;
     /**
-     * True to allow the user to publish or edit the global views. Apps are expected to
-     * commonly set this based on user roles - e.g. `XH.getUser().hasRole('MANAGE_GRID_VIEWS')`.
+     * Optional discriminator for the particular area of an app in which this instance of the
+     * ViewManager appears, for apps that have multiple manager instances that load the same `type`
+     * of views. A particular `currentView` and `pendingValue` will be maintained for each instance,
+     * but all other options and the available library of views will be shared across the `type`.
      */
-    manageGlobal?: Thunkable<boolean>;
+    instance?: string;
     /**
-     * Required discriminator for the particular class of views to be loaded and managed by this
-     * model. Set to something descriptive and specific enough to be identifiable and allow for
-     * different viewManagers to be added to your app in the future - e.g. `portfolioGridView` or
-     * `tradeBlotterDashboard`.
+     * True to allow the user to creat and manage Global views. Apps are expected to commonly set
+     * this based on user roles - e.g. `XH.getUser().hasRole('MANAGE_GRID_VIEWS')`.
      */
-    type: string;
+    manageGlobal?: Thunkable<boolean>;
     /**
-     * Optional sub-discriminator for the particular location in your app this instance of the
-     * view manager appears in. A particular currentView and pendingValue will be maintained by
-     * instance, but all other options, and the available library of views will be shared by type.
+     * True (default) to save pending state to SessionStorage so that it can be restored across
+     * browser refreshes. Unlike auto-save, this does not write to the database.
      */
-    instance?: string;
+    preserveUnsavedChanges?: boolean;
     /**
-     * Optional user-facing display name for the view type, displayed in the ViewManager menu
-     * and associated management dialogs and prompts. Defaulted from `type` if not provided.
+     * User-facing display name for the type of views being managed - e.g. "report" or "dashboard".
+     * Displayed in the `ViewManager` menu and associated management dialogs and prompts.
+     * Defaulted from `type` if not provided.
      */
     typeDisplayName?: string;
     /**
-     * Optional user-facing display name for describing global views. Defaults to 'global'
-     */
-    globalDisplayName?: string;
-    /**
-     * Optional key to pass a method that returns a customized BlueprintJS `menuItem` for listing
-     * views in the ViewManager menu.
+     * Optional render function to customize the BlueprintJS `menuItem` shown for each view in the
+     * ViewManager menu.
      */
     viewMenuItemFn?: (view: ViewInfo, model: ViewManagerModel) => ReactNode;
 }
@@ -124,6 +137,7 @@ export declare class ViewManagerModel<T = PlainObject> extends HoistModel {
     readonly type: string;
     readonly instance: string;
     readonly typeDisplayName: string;
+    readonly defaultDisplayName: string;
     readonly globalDisplayName: string;
     readonly viewMenuItemFn: (view: ViewInfo, model: ViewManagerModel) => ReactNode;
     readonly enableAutoSave: boolean;

package/build/types/desktop/cmp/clipboard/ClipboardButton.d.ts

@@ -3,8 +3,16 @@ import '@xh/hoist/desktop/register';
 export interface ClipboardButtonProps extends ButtonProps {
     /** Function returning the text to copy. May be async. */
     getCopyText: () => string | Promise<string>;
-    /** Message to be displayed in a toast when copy is complete. */
-    successMessage?: string;
+    /**
+     * Message to be displayed in a toast should the copy operation fail, or `true` (default) to
+     * show a toast-based alert from `XH.handleException`. Spec `false` to fail silently.
+     */
+    errorMessage?: string | boolean;
+    /**
+     * Message to be displayed in a toast when copy is complete, or `true` for a default success
+     * confirmation. Default `false`
+     */
+    successMessage?: string | boolean;
 }
 /**
  * Button to copy text to the clipboard.

package/cmp/viewmanager/ViewManagerModel.ts

@@ -52,79 +52,93 @@ export interface ViewUserState {
 
 export interface ViewManagerConfig {
     /**
-     * True (default) to allow user to opt in to automatically saving changes to their current view.
+     * Required discriminator for the particular class of views to be loaded and managed by this
+     * model. Used to set the `type` property on all JSONBlobs persisted by this model.
+     *
+     * Choose something descriptive and specific enough to be identifiable and allow for different
+     * ViewManagers to be added to your app in the future - e.g. `portfolioGridView` or
+     * `tradeBlotterDashboard`.
+     */
+    type: string;
+
+    /**
+     * Optional user-facing qualifier (default "default") for the special in-code default view
+     * option, if enabled. Will be prepended to `typeDisplayName`.
+     *
+     * A use case is to support a ViewManager persisted Dashboard, where the in-code default is an
+     * empty layout, this config is set to "New", and the `typeDisplayName` is set to "Dashboard".
+     * This results in a "New Dashboard" option in the menu, allowing users to quickly access a
+     * blank dashboard to start building from scratch, while forcing a save-as to persist.
      */
+    defaultDisplayName?: string;
+
+    /** True (default) to allow users to opt-in to auto-saving changes to their current view. */
     enableAutoSave?: boolean;
 
     /**
-     * True (default) to allow the user to select a "Default" option that restores all persisted
-     * objects to their in-code defaults. If not enabled, at least one saved view should be created
-     * in advance, so that there is a clear initial selection for users without any private views.
+     * True (default) to allow the user to select a special view from the menu that restores all
+     * persisted objects to their in-code defaults. If not enabled, at least one globally shared
+     * view should be added to provide an initial selection for users without any private views.
      */
     enableDefault?: boolean;
 
     /**
      * True (default) to enable "global" views - i.e. views that are not owned by a user and are
-     * available to all.
+     * available to all. At least some users should have `manageGlobal` set to true to allow
+     * creation and management of these views.
      */
     enableGlobal?: boolean;
 
-    /**
-     * True (default) to allow users to share their views with other users.
-     */
+    /** True (default) to allow users to share their views with other users. */
     enableSharing?: boolean;
 
     /**
-     * True (default) to save pending state to SessionStorage so that it can be restored across
-     * browser refreshes. Unlike auto-save, this does not write to the database.
+     * User-facing qualifier for labelling globally shared views - default "global". A use case
+     * would be to set to the name of the company/team that manages these canonical views, e.g.
+     * "Acme Corp".
      */
-    preserveUnsavedChanges?: boolean;
+    globalDisplayName?: string;
 
     /**
-     * Function to determine the initial view for a user, when no view has already been persisted.
-     * Will be passed a list of views available to the current user.  Implementations where
-     * enableDefault is set false should typically return some view, if any views are
-     * available.  If no view is returned, the control will be forced to fall back on the default.
+     * Function to determine the initial view for a user, when they have no prior view already
+     * persisted. Called with a list of views available to the current user.
      *
-     * Must be set when enableDefault is false.
+     * Must be set when `enableDefault: false`. Developers should take care to return *some* view
+     * in this case, if any are available. If no view is returned, the control will be forced to
+     * fall back to the in-code default.
      */
     initialViewSpec?: (views: ViewInfo[]) => ViewInfo;
 
     /**
-     * True to allow the user to publish or edit the global views. Apps are expected to
-     * commonly set this based on user roles - e.g. `XH.getUser().hasRole('MANAGE_GRID_VIEWS')`.
+     * Optional discriminator for the particular area of an app in which this instance of the
+     * ViewManager appears, for apps that have multiple manager instances that load the same `type`
+     * of views. A particular `currentView` and `pendingValue` will be maintained for each instance,
+     * but all other options and the available library of views will be shared across the `type`.
      */
-    manageGlobal?: Thunkable<boolean>;
+    instance?: string;
 
     /**
-     * Required discriminator for the particular class of views to be loaded and managed by this
-     * model. Set to something descriptive and specific enough to be identifiable and allow for
-     * different viewManagers to be added to your app in the future - e.g. `portfolioGridView` or
-     * `tradeBlotterDashboard`.
+     * True to allow the user to creat and manage Global views. Apps are expected to commonly set
+     * this based on user roles - e.g. `XH.getUser().hasRole('MANAGE_GRID_VIEWS')`.
      */
-    type: string;
+    manageGlobal?: Thunkable<boolean>;
 
     /**
-     * Optional sub-discriminator for the particular location in your app this instance of the
-     * view manager appears in. A particular currentView and pendingValue will be maintained by
-     * instance, but all other options, and the available library of views will be shared by type.
+     * True (default) to save pending state to SessionStorage so that it can be restored across
+     * browser refreshes. Unlike auto-save, this does not write to the database.
      */
-    instance?: string;
+    preserveUnsavedChanges?: boolean;
 
     /**
-     * Optional user-facing display name for the view type, displayed in the ViewManager menu
-     * and associated management dialogs and prompts. Defaulted from `type` if not provided.
+     * User-facing display name for the type of views being managed - e.g. "report" or "dashboard".
+     * Displayed in the `ViewManager` menu and associated management dialogs and prompts.
+     * Defaulted from `type` if not provided.
      */
     typeDisplayName?: string;
 
     /**
-     * Optional user-facing display name for describing global views. Defaults to 'global'
-     */
-    globalDisplayName?: string;
-
-    /**
-     * Optional key to pass a method that returns a customized BlueprintJS `menuItem` for listing
-     * views in the ViewManager menu.
+     * Optional render function to customize the BlueprintJS `menuItem` shown for each view in the
+     * ViewManager menu.
      */
     viewMenuItemFn?: (view: ViewInfo, model: ViewManagerModel) => ReactNode;
 }
@@ -168,6 +182,7 @@ export class ViewManagerModel<T = PlainObject> extends HoistModel {
     readonly type: string;
     readonly instance: string;
     readonly typeDisplayName: string;
+    readonly defaultDisplayName: string;
     readonly globalDisplayName: string;
     readonly viewMenuItemFn: (view: ViewInfo, model: ViewManagerModel) => ReactNode;
     readonly enableAutoSave: boolean;
@@ -240,11 +255,12 @@ export class ViewManagerModel<T = PlainObject> extends HoistModel {
     }
 
     get autoSaveUnavailableReason(): string {
-        const {view, isViewAutoSavable, typeDisplayName, globalDisplayName} = this;
+        const {view, isViewAutoSavable, typeDisplayName, globalDisplayName, defaultDisplayName} =
+            this;
         if (isViewAutoSavable) return null;
         if (view.isGlobal) return `Cannot auto-save ${globalDisplayName} ${typeDisplayName}.`;
         if (view.isShared) return `Cannot auto-save shared ${typeDisplayName}.`;
-        if (view.isDefault) return `Cannot auto-save default ${typeDisplayName}.`;
+        if (view.isDefault) return `Cannot auto-save ${defaultDisplayName} ${typeDisplayName}.`;
         if (XH.identityService.isImpersonating) return `Auto-save disabled during impersonation.`;
         return null;
     }
@@ -282,6 +298,7 @@ export class ViewManagerModel<T = PlainObject> extends HoistModel {
         type,
         instance = 'default',
         typeDisplayName,
+        defaultDisplayName = 'default',
         globalDisplayName = 'global',
         viewMenuItemFn,
         manageGlobal = false,
@@ -303,6 +320,7 @@ export class ViewManagerModel<T = PlainObject> extends HoistModel {
         this.type = type;
         this.instance = instance;
         this.typeDisplayName = lowerCase(typeDisplayName ?? genDisplayName(type));
+        this.defaultDisplayName = defaultDisplayName;
         this.globalDisplayName = globalDisplayName;
         this.viewMenuItemFn = viewMenuItemFn;
         this.manageGlobal = executeIfFunction(manageGlobal) ?? false;

package/desktop/cmp/clipboard/ClipboardButton.ts

@@ -10,12 +10,23 @@ import '@xh/hoist/desktop/register';
 import {Icon} from '@xh/hoist/icon';
 import {withDefault} from '@xh/hoist/utils/js';
 import copy from 'clipboard-copy';
+import {isString} from 'lodash';
 
 export interface ClipboardButtonProps extends ButtonProps {
     /** Function returning the text to copy. May be async. */
     getCopyText: () => string | Promise<string>;
-    /** Message to be displayed in a toast when copy is complete. */
-    successMessage?: string;
+
+    /**
+     * Message to be displayed in a toast should the copy operation fail, or `true` (default) to
+     * show a toast-based alert from `XH.handleException`. Spec `false` to fail silently.
+     */
+    errorMessage?: string | boolean;
+
+    /**
+     * Message to be displayed in a toast when copy is complete, or `true` for a default success
+     * confirmation. Default `false`
+     */
+    successMessage?: string | boolean;
 }
 
 /**
@@ -24,24 +35,36 @@ export interface ClipboardButtonProps extends ButtonProps {
 export const [ClipboardButton, clipboardButton] = hoistCmp.withFactory<ClipboardButtonProps>({
     displayName: 'ClipboardButton',
     model: false,
+
     render(props) {
-        let {icon, onClick, text, getCopyText, successMessage, ...rest} = props;
+        let {icon, onClick, text, getCopyText, errorMessage, successMessage, ...rest} = props;
+        let errMsg = withDefault(errorMessage, true),
+            successMsg = withDefault(successMessage, false);
 
         if (!onClick) {
             onClick = async () => {
-                const {successMessage, getCopyText} = props;
-
                 try {
-                    const text = await getCopyText();
-                    await copy(text);
-                    if (successMessage) {
+                    const copyText = await getCopyText();
+                    await copy(copyText);
+                    if (successMsg) {
+                        successMsg = isString(successMsg) ? successMsg : 'Copied to clipboard';
                         XH.toast({
-                            message: successMessage,
-                            icon: Icon.clipboard()
+                            icon: Icon.clipboard(),
+                            message: successMsg
                         });
                     }
                 } catch (e) {
-                    XH.handleException(e, {showAlert: false});
+                    if (errMsg) {
+                        errMsg = isString(errMsg) ? errMsg : 'Error copying to clipboard';
+                        XH.dangerToast({
+                            icon: Icon.clipboard(),
+                            message: errMsg
+                        });
+                    }
+                    XH.handleException(e, {
+                        message: 'Error copying to clipboard',
+                        showAlert: false
+                    });
                 }
             };
         }

package/desktop/cmp/viewmanager/ViewManager.ts

@@ -130,10 +130,12 @@ export const [ViewManager, viewManager] = hoistCmp.withFactory<ViewManagerProps>
 
 const menuButton = hoistCmp.factory<ViewManagerLocalModel>({
     render({model, icon, ...rest}) {
-        const {view, typeDisplayName, isLoading} = model.parent;
+        const {view, defaultDisplayName, typeDisplayName, isLoading} = model.parent;
         return button({
             className: 'xh-view-manager__menu-button',
-            text: view.isDefault ? `Default ${startCase(typeDisplayName)}` : view.name,
+            text: view.isDefault
+                ? `${startCase(defaultDisplayName)} ${startCase(typeDisplayName)}`
+                : view.name,
             icon: !isLoading
                 ? icon
                 : box({

package/desktop/cmp/viewmanager/ViewMenu.ts

@@ -36,7 +36,7 @@ export const viewMenu = hoistCmp.factory<ViewManagerLocalModel>({
 });
 
 function getNavMenuItems(model: ViewManagerModel): ReactNode[] {
-    const {enableDefault, view, typeDisplayName, globalDisplayName} = model,
+    const {enableDefault, view, defaultDisplayName, typeDisplayName, globalDisplayName} = model,
         ownedViews = groupBy(filter(model.ownedViews, 'isPinned'), 'group'),
         globalViews = groupBy(filter(model.globalViews, 'isPinned'), 'group'),
         sharedViews = groupBy(filter(model.sharedViews, 'isPinned'), 'owner'),
@@ -69,7 +69,7 @@ function getNavMenuItems(model: ViewManagerModel): ReactNode[] {
             menuItem({
                 className: 'xh-view-manager__menu-item',
                 icon: view.isDefault ? Icon.check() : Icon.placeholder(),
-                text: `Default ${startCase(typeDisplayName)}`,
+                text: `${startCase(defaultDisplayName)} ${startCase(typeDisplayName)}`,
                 onClick: () => model.selectViewAsync(null).catchDefault()
             })
         );

package/desktop/cmp/viewmanager/dialog/ManageDialogModel.ts

@@ -7,7 +7,7 @@
 
 import {badge} from '@xh/hoist/cmp/badge';
 import {dateTimeCol, GridAutosizeMode, GridModel} from '@xh/hoist/cmp/grid';
-import {fragment, hbox, p, strong} from '@xh/hoist/cmp/layout';
+import {br, fragment, hbox, p, strong} from '@xh/hoist/cmp/layout';
 import {TabContainerModel} from '@xh/hoist/cmp/tab';
 import {ViewInfo, ViewManagerModel, ViewUpdateSpec} from '@xh/hoist/cmp/viewmanager';
 import {HoistModel, LoadSpec, managed, TaskObserver, XH} from '@xh/hoist/core';
@@ -338,10 +338,15 @@ export class ManageDialogModel extends HoistModel {
                         model: this.ownedGridModel,
                         helpText: fragment(
                             Icon.user(),
-                            `This tab shows ${views} you have created. Pinned ${views} are shown in your menu for quick access. Set a group on ${views} to show them together in a sub-menu. `,
-                            enableSharing
-                                ? `Opt-in to sharing any of your ${views} to make them discoverable by other users.`
-                                : ''
+                            `This tab shows ${views} you have created.`,
+                            br(),
+                            `Pin ${views} to your menu for quick access. Use groups to nest them under sub-menus.`,
+                            ...(enableSharing
+                                ? [
+                                      br(),
+                                      `Opt-in to sharing any of your ${views} to make them discoverable by other users.`
+                                  ]
+                                : [''])
                         )
                     })
                 }
@@ -355,7 +360,9 @@ export class ManageDialogModel extends HoistModel {
                     model: this.globalGridModel,
                     helpText: fragment(
                         Icon.globe(),
-                        `This tab shows ${globalViews} available to everyone. ${capitalize(globalViews)} can be pinned by default so they appear automatically in everyone's menu, but you can choose which ${views} you would like to see by pinning/unpinning them at any time.`
+                        `This tab shows ${globalViews} available to everyone.`,
+                        br(),
+                        `${capitalize(globalViews)} can be set to appear automatically in everyone's menu, but you can choose which ${views} you would like to see by pinning/unpinning them at any time.`
                     )
                 })
             });
@@ -369,7 +376,9 @@ export class ManageDialogModel extends HoistModel {
                     model: this.sharedGridModel,
                     helpText: fragment(
                         Icon.users(),
-                        `This tab shows ${views} shared by other ${XH.appName} users. You can pin these ${views} to add them to your menu and access them directly. Only the owner will be able to save changes to a shared ${view}, but you can save as a copy to make it your own.`
+                        `This tab shows ${views} shared by other ${XH.appName} users.`,
+                        br(),
+                        `You can pin these ${views} to your menu for quick access. Only the owner will be able to save changes to a shared ${view}, but you can save a copy to make it your own.`
                     )
                 })
             });

package/desktop/cmp/viewmanager/dialog/ViewPanel.ts

@@ -79,10 +79,12 @@ export const viewPanel = hoistCmp.factory({
                         }),
                         formField({
                             field: 'isDefaultPinned',
-                            label: 'Pin by default?',
-                            labelWidth: 110,
+                            label: null,
                             inline: true,
-                            item: switchInput(),
+                            item: switchInput({
+                                label: `Pin to everyone's menu by default`,
+                                labelSide: 'left'
+                            }),
                             omit: !isGlobal || !isEditable
                         }),
                         vspacer(),

package/package.json

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