@xh/hoist 75.0.0-SNAPSHOT.1753490062755 → 75.0.0-SNAPSHOT.1753722797428

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/core/AppSpec.d.ts

@@ -1,85 +1,96 @@
 import { HoistAppModel, HoistAuthModel, ElementFactory, HoistProps } from '@xh/hoist/core';
 import { Component, ComponentClass, FunctionComponent } from 'react';
 /**
- * Specification for a client-side Hoist application.
- * Passed to XH.renderApp() to kick-off app rendering and available thereafter as `XH.appSpec`.
+ * Spec for a client-side Hoist application. A config matching this class's shape is provided
+ * to {@link XHApi.renderApp} to kick-off app rendering and is available thereafter as `XH.appSpec`.
  */
 export declare class AppSpec<T extends HoistAppModel = HoistAppModel> {
+    /**
+     * AuthModel class for the application. Note this is a reference to the class itself, not an
+     * instance, and must extend {@link HoistAuthModel}. If not provided, Hoist will fallback to
+     * the superclass implementation, but note that class would only be suitable for fully
+     * transparent SSO based solutions such as NTLM. Common patterns such as OAuth will require an
+     * extended implementation.
+     */
+    authModelClass?: new () => HoistAuthModel;
+    /**
+     * Method for determining if user may access the app. If a string, will be interpreted as the
+     * role required for basic UI access. Return false to show a generated lockout message, or use
+     * the object form to provide a custom message.
+     */
+    checkAccess: string | ((user: object) => boolean | {
+        hasAccess: boolean;
+        message: string;
+    });
     /**
      *  Short code for this particular JS client application.
+     *
      *  Will default to the `appCode` specified within the project's Webpack config, but can be
      *  set to a more specific value (e.g. 'myAppMobile') to identify the client app in common
-     *  code or configs.
+     *  code or configs that support distinct settings for different client apps.
      */
     clientAppCode?: string;
     /**
      * Display name for this particular JS client application.
+     *
      * As with `clientAppCode` above, this will default to the global `appName` specified by
      * the project's Webpack config, but can be set here to a more specific value (e.g.
      * 'MyApp Mobile').
      */
     clientAppName?: string;
     /**
-     * Root Model class for the application. Note this is a reference to the class itself, not an
-     * instance, and must extend {@link HoistAppModel}.
-     */
-    modelClass: new () => T;
-    /**
-     * AuthModel class for the application.  Note this is a reference to the class itself, not an
-     * instance, and must extend {@link HoistAuthModel}.
-     */
-    authModelClass?: new () => HoistAuthModel;
-    /**
-     * Root HoistComponent for the application. Despite the name, functional components are fully
-     * supported and expected.
+     * Root HoistComponent for the application.
+     * Despite the name, functional components are fully supported and expected.
      */
     componentClass: ComponentClass<HoistProps> | FunctionComponent<HoistProps>;
     /**
      * Container component to be used to host this application.
-     * This class determines the platform used by Hoist. The value should be imported from
+     *
+     * This class determines the platform used by Hoist - almost all apps will import and specify
      * either `@xh/hoist/desktop/AppContainer` or `@xh/hoist/mobile/AppContainer`.
      */
     containerClass: ComponentClass<HoistProps> | FunctionComponent<HoistProps>;
-    /** True if the app should use the Hoist mobile toolkit.*/
-    isMobileApp: boolean;
-    /** True to show a login form on initialization when not authenticated. (default false) */
-    enableLoginForm?: boolean;
     /**
-     * True to show logout options in the app, for apps with auth schemes that can support this
-     * operation (e.g. OAuth). (default false)
+     * True to disable Field-level XSS protection by default across all Stores/Fields in the app.
+     * For use with secure, internal apps that do not display arbitrary/external user input and
+     * have tight performance tolerances and/or load very large record sets.
+     * @see FieldSpec.disableXssProtection
      */
-    enableLogout?: boolean;
+    disableXssProtection?: boolean;
     /**
-     * Method for determining if user may access the app.
-     * If a string, will be interpreted as the role required for basic UI access.
+     * True to show a login form on initialization when not authenticated. Default is `false` as
+     * most Hoist applications are expected to use OAuth or SSO for authn.
      */
-    checkAccess: string | ((user: object) => boolean | {
-        hasAccess: boolean;
-        message: string;
-    });
+    enableLoginForm?: boolean;
     /**
-     *  Write a track log statement after the app has loaded and fully initialized?
-     *  Message will include elapsed time of asset loading and init.
+     * True to show logout options in the app, for apps with auth schemes that can support this
+     * operation (e.g. OAuth). Default is `false` as most Hoist applications are expected to use
+     * SSO or to run in internal environments where logout is not required / typical.
      */
-    trackAppLoad?: boolean;
-    /** True to enable Hoist websocket connectivity. (default false) */
-    webSocketsEnabled?: boolean;
+    enableLogout?: boolean;
     /**
-     * Optional custom Component to display when App has been suspended. The component will
-     * receive a single prop -- onReactivate -- a callback called when the user has acknowledged
+     * Optional custom Component to display when the app has been suspended. The component will
+     * receive a single `onReactivate` prop, a no-arg callback fired when the user has acknowledged
      * the suspension and wishes to reload the app.
      */
     idlePanel?: ElementFactory | FunctionComponent | Component;
+    /** True if the app should use the Hoist mobile toolkit.*/
+    isMobileApp: boolean;
     /**
      * Optional custom Component to display when the user is denied access to app. Intended for
      * apps that implement custom auth flows. See also `lockoutMessage` for a more lightweight
      * customization option.
      */
     lockoutPanel?: ElementFactory | FunctionComponent | Component;
-    /** Optional message to show on login form (see showLoginForm). */
-    loginMessage?: string;
     /** Optional message to show users when denied access to app. */
     lockoutMessage?: string;
+    /** Optional message to show on login form, if `showLoginForm: true`. */
+    loginMessage?: string;
+    /**
+     * Root Model class for the application. Note this is a reference to the class itself, not an
+     * instance, and must extend {@link HoistAppModel}.
+     */
+    modelClass: new () => T;
     /**
      * True to show the built-in browser context menu when no app-specific menu would be shown
      * (e.g. from a Grid). False (the default) prevents the browser menu from being shown anywhere
@@ -87,30 +98,30 @@ export declare class AppSpec<T extends HoistAppModel = HoistAppModel> {
      */
     showBrowserContextMenu?: boolean;
     /**
-     * True to disable Field-level XSS protection by default across all Stores/Fields in the app.
-     * For use with secure, internal apps that do not display arbitrary/external user input and
-     * have tight performance tolerances and/or load very large record sets.
-     * @see FieldConfig.disableXssProtection
+     *  True (default) to write a track log statement after the app has loaded and fully
+     *  initialized, including a breakdown of elapsed time throughout the init process.
      */
-    disableXssProtection?: boolean;
-    constructor({ clientAppCode, clientAppName, modelClass, componentClass, containerClass, authModelClass, isMobileApp, checkAccess, enableLoginForm, enableLogout, trackAppLoad, webSocketsEnabled, idlePanel, lockoutPanel, loginMessage, lockoutMessage, showBrowserContextMenu, disableXssProtection }: {
+    trackAppLoad?: boolean;
+    /** True to enable Hoist websocket connectivity. */
+    webSocketsEnabled?: boolean;
+    constructor({ authModelClass, checkAccess, clientAppCode, clientAppName, componentClass, containerClass, disableXssProtection, enableLoginForm, enableLogout, idlePanel, isMobileApp, lockoutMessage, lockoutPanel, loginMessage, modelClass, showBrowserContextMenu, trackAppLoad, webSocketsEnabled }: {
+        authModelClass?: typeof HoistAuthModel;
+        checkAccess: any;
         clientAppCode?: string;
         clientAppName?: string;
-        modelClass: any;
         componentClass: any;
         containerClass: any;
-        authModelClass?: typeof HoistAuthModel;
-        isMobileApp: any;
-        checkAccess: any;
+        disableXssProtection?: boolean;
         enableLoginForm?: boolean;
         enableLogout?: boolean;
-        trackAppLoad?: boolean;
-        webSocketsEnabled?: boolean;
         idlePanel?: any;
+        isMobileApp: any;
+        lockoutMessage?: any;
         lockoutPanel?: any;
         loginMessage?: any;
-        lockoutMessage?: any;
+        modelClass: any;
         showBrowserContextMenu?: boolean;
-        disableXssProtection?: boolean;
+        trackAppLoad?: boolean;
+        webSocketsEnabled?: boolean;
     });
 }

package/build/types/core/HoistAuthModel.d.ts

@@ -2,13 +2,13 @@ import { HoistModel, PlainObject } from './';
 /**
  *  Base class for managing authentication lifecycle.
  *
- *  Hoist will consult this model early in  the initialization sequence, prior to full Hoist
+ *  Hoist will consult this model early in the initialization sequence, prior to full Hoist
  *  initialization. This means that several core services (identity, configs, prefs) will *not* be
  *  available, but it provides the app a hook to do early service initialization or other work to
  *  support flows such as OAuth.
  *
  *  The base implementation of this class is minimal and would be adequate only for fully
- *  transparent SSO based solutions such as NTLM.  Applications wishing to provide custom
+ *  transparent SSO based solutions such as NTLM. Applications wishing to provide custom
  *  authentication should spec an extended version of this class in the {@link AppSpec} passed to
  *  {@link XHApi#renderApp}.
  */

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/core/AppSpec.ts

@@ -10,20 +10,38 @@ import {isFunction, isNil, isString} from 'lodash';
 import {Component, ComponentClass, FunctionComponent} from 'react';
 
 /**
- * Specification for a client-side Hoist application.
- * Passed to XH.renderApp() to kick-off app rendering and available thereafter as `XH.appSpec`.
+ * Spec for a client-side Hoist application. A config matching this class's shape is provided
+ * to {@link XHApi.renderApp} to kick-off app rendering and is available thereafter as `XH.appSpec`.
  */
 export class AppSpec<T extends HoistAppModel = HoistAppModel> {
+    /**
+     * AuthModel class for the application. Note this is a reference to the class itself, not an
+     * instance, and must extend {@link HoistAuthModel}. If not provided, Hoist will fallback to
+     * the superclass implementation, but note that class would only be suitable for fully
+     * transparent SSO based solutions such as NTLM. Common patterns such as OAuth will require an
+     * extended implementation.
+     */
+    authModelClass?: new () => HoistAuthModel;
+
+    /**
+     * Method for determining if user may access the app. If a string, will be interpreted as the
+     * role required for basic UI access. Return false to show a generated lockout message, or use
+     * the object form to provide a custom message.
+     */
+    checkAccess: string | ((user: object) => boolean | {hasAccess: boolean; message: string});
+
     /**
      *  Short code for this particular JS client application.
+     *
      *  Will default to the `appCode` specified within the project's Webpack config, but can be
      *  set to a more specific value (e.g. 'myAppMobile') to identify the client app in common
-     *  code or configs.
+     *  code or configs that support distinct settings for different client apps.
      */
     clientAppCode?: string;
 
     /**
      * Display name for this particular JS client application.
+     *
      * As with `clientAppCode` above, this will default to the global `appName` specified by
      * the project's Webpack config, but can be set here to a more specific value (e.g.
      * 'MyApp Mobile').
@@ -31,64 +49,50 @@ export class AppSpec<T extends HoistAppModel = HoistAppModel> {
     clientAppName?: string;
 
     /**
-     * Root Model class for the application. Note this is a reference to the class itself, not an
-     * instance, and must extend {@link HoistAppModel}.
-     */
-    modelClass: new () => T;
-
-    /**
-     * AuthModel class for the application.  Note this is a reference to the class itself, not an
-     * instance, and must extend {@link HoistAuthModel}.
-     */
-    authModelClass?: new () => HoistAuthModel;
-
-    /**
-     * Root HoistComponent for the application. Despite the name, functional components are fully
-     * supported and expected.
+     * Root HoistComponent for the application.
+     * Despite the name, functional components are fully supported and expected.
      */
     componentClass: ComponentClass<HoistProps> | FunctionComponent<HoistProps>;
 
     /**
      * Container component to be used to host this application.
-     * This class determines the platform used by Hoist. The value should be imported from
+     *
+     * This class determines the platform used by Hoist - almost all apps will import and specify
      * either `@xh/hoist/desktop/AppContainer` or `@xh/hoist/mobile/AppContainer`.
      */
     containerClass: ComponentClass<HoistProps> | FunctionComponent<HoistProps>;
 
-    /** True if the app should use the Hoist mobile toolkit.*/
-    isMobileApp: boolean;
-
-    /** True to show a login form on initialization when not authenticated. (default false) */
-    enableLoginForm?: boolean;
-
     /**
-     * True to show logout options in the app, for apps with auth schemes that can support this
-     * operation (e.g. OAuth). (default false)
+     * True to disable Field-level XSS protection by default across all Stores/Fields in the app.
+     * For use with secure, internal apps that do not display arbitrary/external user input and
+     * have tight performance tolerances and/or load very large record sets.
+     * @see FieldSpec.disableXssProtection
      */
-    enableLogout?: boolean;
+    disableXssProtection?: boolean;
 
     /**
-     * Method for determining if user may access the app.
-     * If a string, will be interpreted as the role required for basic UI access.
+     * True to show a login form on initialization when not authenticated. Default is `false` as
+     * most Hoist applications are expected to use OAuth or SSO for authn.
      */
-    checkAccess: string | ((user: object) => boolean | {hasAccess: boolean; message: string});
+    enableLoginForm?: boolean;
 
     /**
-     *  Write a track log statement after the app has loaded and fully initialized?
-     *  Message will include elapsed time of asset loading and init.
+     * True to show logout options in the app, for apps with auth schemes that can support this
+     * operation (e.g. OAuth). Default is `false` as most Hoist applications are expected to use
+     * SSO or to run in internal environments where logout is not required / typical.
      */
-    trackAppLoad?: boolean;
-
-    /** True to enable Hoist websocket connectivity. (default false) */
-    webSocketsEnabled?: boolean;
+    enableLogout?: boolean;
 
     /**
-     * Optional custom Component to display when App has been suspended. The component will
-     * receive a single prop -- onReactivate -- a callback called when the user has acknowledged
+     * Optional custom Component to display when the app has been suspended. The component will
+     * receive a single `onReactivate` prop, a no-arg callback fired when the user has acknowledged
      * the suspension and wishes to reload the app.
      */
     idlePanel?: ElementFactory | FunctionComponent | Component;
 
+    /** True if the app should use the Hoist mobile toolkit.*/
+    isMobileApp: boolean;
+
     /**
      * Optional custom Component to display when the user is denied access to app. Intended for
      * apps that implement custom auth flows. See also `lockoutMessage` for a more lightweight
@@ -96,12 +100,18 @@ export class AppSpec<T extends HoistAppModel = HoistAppModel> {
      */
     lockoutPanel?: ElementFactory | FunctionComponent | Component;
 
-    /** Optional message to show on login form (see showLoginForm). */
-    loginMessage?: string;
-
     /** Optional message to show users when denied access to app. */
     lockoutMessage?: string;
 
+    /** Optional message to show on login form, if `showLoginForm: true`. */
+    loginMessage?: string;
+
+    /**
+     * Root Model class for the application. Note this is a reference to the class itself, not an
+     * instance, and must extend {@link HoistAppModel}.
+     */
+    modelClass: new () => T;
+
     /**
      * True to show the built-in browser context menu when no app-specific menu would be shown
      * (e.g. from a Grid). False (the default) prevents the browser menu from being shown anywhere
@@ -110,67 +120,67 @@ export class AppSpec<T extends HoistAppModel = HoistAppModel> {
     showBrowserContextMenu?: boolean;
 
     /**
-     * True to disable Field-level XSS protection by default across all Stores/Fields in the app.
-     * For use with secure, internal apps that do not display arbitrary/external user input and
-     * have tight performance tolerances and/or load very large record sets.
-     * @see FieldConfig.disableXssProtection
+     *  True (default) to write a track log statement after the app has loaded and fully
+     *  initialized, including a breakdown of elapsed time throughout the init process.
      */
-    disableXssProtection?: boolean;
+    trackAppLoad?: boolean;
+
+    /** True to enable Hoist websocket connectivity. */
+    webSocketsEnabled?: boolean;
 
     constructor({
+        authModelClass = HoistAuthModel,
+        checkAccess,
         clientAppCode = XH.appCode,
         clientAppName = XH.appName,
-        modelClass,
         componentClass,
         containerClass,
-        authModelClass = HoistAuthModel,
-        isMobileApp,
-        checkAccess,
+        disableXssProtection = false,
         enableLoginForm = false,
         enableLogout = false,
-        trackAppLoad = true,
-        webSocketsEnabled = false,
         idlePanel = null,
+        isMobileApp,
+        lockoutMessage = null,
         lockoutPanel = null,
         loginMessage = null,
-        lockoutMessage = null,
+        modelClass,
         showBrowserContextMenu = false,
-        disableXssProtection = false
+        trackAppLoad = true,
+        webSocketsEnabled = false
     }) {
-        throwIf(!modelClass, 'A Hoist App must define a modelClass.');
         throwIf(!componentClass, 'A Hoist App must define a componentClass');
-        throwIf(isNil(isMobileApp), 'A Hoist App must define isMobileApp');
+
         throwIf(
             !containerClass,
-            `Please import and provide containerClass from "@xh/hoist/${
-                isMobileApp ? 'mobile' : 'desktop'
-            }/AppContainer".`
+            `Please import and provide containerClass from "@xh/hoist/${isMobileApp ? 'mobile' : 'desktop'}/AppContainer".`
         );
 
+        throwIf(!modelClass, 'A Hoist App must define a modelClass.');
+
+        throwIf(isNil(isMobileApp), 'A Hoist App must define isMobileApp');
+
         throwIf(
             !isString(checkAccess) && !isFunction(checkAccess),
             'A Hoist App must specify a required role string or a function for checkAccess.'
         );
 
+        this.authModelClass = authModelClass;
+        this.checkAccess = checkAccess;
         this.clientAppCode = clientAppCode;
         this.clientAppName = clientAppName;
-
-        this.modelClass = modelClass;
         this.componentClass = componentClass;
         this.containerClass = containerClass;
-        this.authModelClass = authModelClass;
-        this.isMobileApp = isMobileApp;
-        this.checkAccess = checkAccess;
-
-        this.trackAppLoad = trackAppLoad;
-        this.webSocketsEnabled = webSocketsEnabled;
+        this.disableXssProtection = disableXssProtection;
+        this.enableLoginForm = enableLoginForm;
+        this.enableLogout = enableLogout;
         this.idlePanel = idlePanel;
+        this.isMobileApp = isMobileApp;
+        this.lockoutMessage = lockoutMessage;
         this.lockoutPanel = lockoutPanel;
-        this.enableLogout = enableLogout;
-        this.enableLoginForm = enableLoginForm;
         this.loginMessage = loginMessage;
-        this.lockoutMessage = lockoutMessage;
+        this.modelClass = modelClass;
         this.showBrowserContextMenu = showBrowserContextMenu;
-        this.disableXssProtection = disableXssProtection;
+        this.trackAppLoad = trackAppLoad;
+        this.webSocketsEnabled = webSocketsEnabled;
     }
 }

package/core/HoistAuthModel.ts

@@ -9,13 +9,13 @@ import {HoistModel, PlainObject, XH} from './';
 /**
  *  Base class for managing authentication lifecycle.
  *
- *  Hoist will consult this model early in  the initialization sequence, prior to full Hoist
+ *  Hoist will consult this model early in the initialization sequence, prior to full Hoist
  *  initialization. This means that several core services (identity, configs, prefs) will *not* be
  *  available, but it provides the app a hook to do early service initialization or other work to
  *  support flows such as OAuth.
  *
  *  The base implementation of this class is minimal and would be adequate only for fully
- *  transparent SSO based solutions such as NTLM.  Applications wishing to provide custom
+ *  transparent SSO based solutions such as NTLM. Applications wishing to provide custom
  *  authentication should spec an extended version of this class in the {@link AppSpec} passed to
  *  {@link XHApi#renderApp}.
  */

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/package.json

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