@xh/hoist 76.0.0-SNAPSHOT.1756219543970 → 76.0.0-SNAPSHOT.1756431654493

package/CHANGELOG.md

@@ -17,12 +17,15 @@
 * Handled an edge-case `ViewManager` bug where `enableDefault` changed to `false` after some user
   state had already been persisted w/users pointed at in-code default view. The manager now calls
   its configured `initialViewSpec` function as expected in this case.
-  
-* `XH.restoreDefaultsAsync` will now clear basic view state.  Views themselves will be preserved.
-  Requires hoist-core v31.2
+* `XH.restoreDefaultsAsync` will now clear basic ViewManager state, notably last active view. User
+  views themselves will be preserved. Requires `hoist-core >= 31.2`.
 
 ### ⚙️ Technical
 
+* Hoist's client-side logging utilities are now governed by the new `XH.logLevel` property, defining
+  a logging severity threshold for the app. Default level is 'info', preventing memory usage and
+  performance impacts from verbose logging on level 'debug'. This level can be changed at runtime
+  for troubleshooting. See documentation within `LogUtils.ts` for more info.
 * Added control to trigger browser GC from app footer. Useful for troubleshooting memory issues.
   Requires running chromium-based browser via e.g. `start chrome --js-flags="--expose-gc`.
 

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

@@ -2,6 +2,7 @@ import { RouterModel } from '@xh/hoist/appcontainer/RouterModel';
 import { HoistAuthModel } from '@xh/hoist/core/HoistAuthModel';
 import { Store } from '@xh/hoist/data';
 import { AlertBannerService, AutoRefreshService, ChangelogService, ConfigService, EnvironmentService, FetchOptions, FetchService, GridAutosizeService, GridExportService, IdentityService, IdleService, InspectorService, JsonBlobService, LocalStorageService, PrefService, SessionStorageService, TrackService, WebSocketService, ClientHealthService } from '@xh/hoist/svc';
+import { LogLevel } from '@xh/hoist/utils/js';
 import { Router, State } from 'router5';
 import { CancelFn } from 'router5/types/types/base';
 import { SetOptional } from 'type-fest';
@@ -177,6 +178,18 @@ export declare class XHApi {
      * @see HoistAuthModel.logoutAsync
      */
     logoutAsync(): Promise<void>;
+    /**
+     * Current minimum severity for Hoist log utils (default 'info').
+     * Messages logged via managed Hoist log utils with lower severity will be ignored.
+     */
+    get logLevel(): LogLevel;
+    /**
+     * Set the minimum severity for Hoist log utils until the page is refreshed. Optionally persist
+     * this adjustment to sessionStorage to maintain for the lifetime of the browser tab.
+     *
+     * Hint: call this method from the console to adjust your app's log level while troubleshooting.
+     */
+    setLogLevel(level: LogLevel, persistInSessionStorage?: boolean): void;
     /**
      * Main entry point to start the client app - initializes and renders application code.
      * Call from the app's entry-point file within your project's `/client-app/src/apps/` folder.

package/build/types/desktop/cmp/rest/RestGrid.d.ts

@@ -6,19 +6,28 @@ import { RestGridModel } from './RestGridModel';
 export interface RestGridProps extends HoistProps<RestGridModel>, Omit<PanelProps, 'model' | 'modelConfig' | 'modelRef'> {
     /**
      * This constitutes an 'escape hatch' for applications that need to get to the underlying
-     * ag-Grid API.  It should be used with care. Settings made here might be overwritten and/or
-     * interfere with the implementation of this component and its use of the ag-Grid API.
+     * AG Grid API. Use with care - settings made here might be overwritten and/or interfere with
+     * the implementation of this component and its use of AG Grid.
      */
     agOptions?: PlainObject;
-    /** Optional components rendered adjacent to the top toolbar's action buttons */
-    extraToolbarItems?: Some<ReactNode> | (() => Some<ReactNode>);
     /**
-     * Mask to render on this Component. Defaults to true, which renders a standard
-     * Hoist mask. Also can be set to false for no mask, or passed an element
-     * specifying a Mask instance.
+     * Optional components rendered adjacent to the top toolbar's action buttons.
+     * See also {@link tbar} to take full control of the toolbar.
      */
-    mask?: ReactElement | boolean;
+    extraToolbarItems?: Some<ReactNode> | (() => Some<ReactNode>);
     /** Classname to be passed to RestForm. */
     formClassName?: string;
+    /**
+     * Mask to render on this Component. Defaults to true, which renders a standard Hoist mask.
+     * Set to null/false for no mask, or pass a fully customized mask element.
+     */
+    mask?: ReactElement | boolean;
+    /**
+     * A custom toolbar to be docked above the grid. Note that this supersedes the default
+     * toolbar, meaning the `extraToolbarItems` prop will be ignored, as will the `RestGridModel`
+     * configs `toolbarActions`, `filterFields`, and `showRefreshButton`. If specified as an array,
+     * will be passed as children to a Toolbar component.
+     */
+    tbar?: Some<ReactNode>;
 }
 export declare const RestGrid: import("react").FC<RestGridProps>, restGrid: import("@xh/hoist/core").ElementFactory<RestGridProps>;

package/build/types/utils/js/LogUtils.d.ts

@@ -1,4 +1,20 @@
 import { Some } from '@xh/hoist/core';
+/**
+ * Utility functions providing managed, structured logging to Hoist apps.
+ *
+ * Essentially a wrapper around the browser console supporting logging levels, timing, and
+ * miscellaneous Hoist display conventions.
+ *
+ * Objects extending `HoistBase` need not import these functions directly, as they are available
+ * via delegates on `HoistBase`.
+ *
+ * Hoist sets its minimum severity level to 'info' by default.  This prevents performance or
+ * memory impacts that might result from verbose debug logging.  This can be adjusted by calling
+ * XH.logLevel from the console.
+ */
+/** Severity Level for log statement */
+export type LogLevel = 'error' | 'warn' | 'info' | 'debug';
+/** Object identifying the source of log statement.  Typically, a javascript class */
 export type LogSource = string | {
     displayName: string;
 } | {
@@ -6,6 +22,20 @@ export type LogSource = string | {
         name: string;
     };
 };
+/**
+ * Current minimum severity for Hoist log utils (default 'info').
+ * Messages logged via managed Hoist log utils with lower severity will be ignored.
+ *
+ * @internal - use public `XH.logLevel`.
+ */
+export declare function getLogLevel(): LogLevel;
+/**
+ * Set the minimum severity for Hoist log utils until the page is refreshed. Optionally persist
+ * this adjustment to sessionStorage to maintain for the lifetime of the browser tab.
+ *
+ * @internal - use public `XH.setLogLevel()`.
+ */
+export declare function setLogLevel(level: LogLevel, persistInSessionStorage?: boolean): void;
 /**
  * Time and log execution of a function to `console.info()`.
  *
@@ -50,5 +80,3 @@ export declare function logError(msgs: Some<unknown>, source?: LogSource): unkno
  * @param source - class, function or string to label the source of the message
  */
 export declare function logWarn(msgs: Some<unknown>, source?: LogSource): unknown;
-/** Parse a LogSource in to a canonical string label. */
-export declare function parseSource(source: LogSource): string;

package/cmp/grid/impl/Utils.ts

@@ -6,6 +6,7 @@
  */
 import {Column, ColumnGroup, ColumnRenderer, GroupRowRenderer} from '@xh/hoist/cmp/grid';
 import {HeaderClassParams} from '@xh/hoist/kit/ag-grid';
+import {logWarn} from '@xh/hoist/utils/js';
 import {castArray, isFunction} from 'lodash';
 
 /** @internal */
@@ -18,7 +19,7 @@ export function managedRenderer<T extends ColumnRenderer | GroupRowRenderer>(
         try {
             return fn.apply(null, arguments);
         } catch (e) {
-            console.warn(`Renderer for '${identifier}' has thrown an error`, e);
+            logWarn([`Renderer for '${identifier}' has thrown an error`, e]);
             return '#ERROR';
         }
     } as unknown as T;

package/core/HoistComponent.ts

@@ -25,7 +25,7 @@ import {
     formatSelector,
     HoistModel
 } from './model';
-import {throwIf, warnIf, withDefault} from '@xh/hoist/utils/js';
+import {logError, throwIf, warnIf, withDefault} from '@xh/hoist/utils/js';
 import {getLayoutProps, useOnMount, useOnUnmount} from '@xh/hoist/utils/react';
 import classNames from 'classnames';
 import {isFunction, isPlainObject, isObject} from 'lodash';
@@ -285,11 +285,11 @@ function wrapWithModel(render: RenderFn, cfg: Config): RenderFn {
 
         // 2) Validate
         if (!model && !spec.optional && spec instanceof UsesSpec) {
-            console.error(`
-                Failed to find model with selector '${formatSelector(spec.selector)}' for
-                component '${cfg.displayName}'. Ensure the proper model is available via context, or
-                specify explicitly using the 'model' prop.
-            `);
+            logError(
+                `Failed to find model with selector '${formatSelector(spec.selector)}'. Ensure the
+                proper model is available via context, or specify using the 'model' prop.`,
+                cfg.displayName
+            );
             return cmpErrDisplay({...getLayoutProps(props), item: 'No model found'});
         }
 
@@ -408,10 +408,11 @@ function lookupModel(props: HoistProps, modelLookup: ModelLookup, cfg: Config):
     // 2) props - instance
     if (model) {
         if (!model.isHoistModel || !model.matchesSelector(selector, true)) {
-            console.error(
-                `Incorrect model passed to '${cfg.displayName}'.
+            logError(
+                `Incorrect model passed.
                 Expected: ${formatSelector(selector)}
-                Received: ${model.constructor.name}`
+                Received: ${model.constructor.name}`,
+                cfg.displayName
             );
             model = null;
         }

package/core/XH.ts

@@ -31,6 +31,7 @@ import {
     WebSocketService,
     ClientHealthService
 } from '@xh/hoist/svc';
+import {getLogLevel, setLogLevel, LogLevel} from '@xh/hoist/utils/js';
 import {camelCase, flatten, isString, uniqueId} from 'lodash';
 import {Router, State} from 'router5';
 import {CancelFn} from 'router5/types/types/base';
@@ -360,6 +361,24 @@ export class XHApi {
         this.reloadApp();
     }
 
+    /**
+     * Current minimum severity for Hoist log utils (default 'info').
+     * Messages logged via managed Hoist log utils with lower severity will be ignored.
+     */
+    get logLevel(): LogLevel {
+        return getLogLevel();
+    }
+
+    /**
+     * Set the minimum severity for Hoist log utils until the page is refreshed. Optionally persist
+     * this adjustment to sessionStorage to maintain for the lifetime of the browser tab.
+     *
+     * Hint: call this method from the console to adjust your app's log level while troubleshooting.
+     */
+    setLogLevel(level: LogLevel, persistInSessionStorage: boolean = false) {
+        setLogLevel(level, persistInSessionStorage);
+    }
+
     //----------------------
     // App lifecycle support
     //----------------------

package/core/exception/ExceptionHandler.ts

@@ -312,7 +312,7 @@ export class ExceptionHandler {
     }
 
     private logException(e: HoistException, opts: ExceptionHandlerOptions) {
-        return opts.showAsError ? console.error(opts.message, e) : console.debug(opts.message);
+        return opts.showAsError ? logError([opts.message, e], this) : logDebug(opts.message, this);
     }
 
     private parseOptions(

package/core/load/LoadSupport.ts

@@ -135,7 +135,7 @@ export async function loadAllAsync(objs: Loadable[], loadSpec?: LoadSpec | any)
         ret = await Promise.allSettled(promises);
 
     ret.filter(it => it.status === 'rejected').forEach((err: any) =>
-        console.error('Failed to Load Object', err.reason)
+        logError(['Failed to Load Object', err.reason])
     );
 
     return ret;

package/data/filter/Utils.ts

@@ -7,6 +7,7 @@
 
 import {Some} from '@xh/hoist/core';
 import {CompoundFilter, FunctionFilter} from '@xh/hoist/data';
+import {logError} from '@xh/hoist/utils/js';
 import {castArray, flatMap, groupBy, isArray, isFunction} from 'lodash';
 import {FieldFilter} from './FieldFilter';
 import {Filter} from './Filter';
@@ -55,7 +56,7 @@ export function parseFilter(spec: FilterLike): Filter {
         }
     }
 
-    console.error('Unable to identify filter type:', s);
+    logError(['Unable to identify filter type:', s]);
     return null;
 }
 

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

@@ -7,7 +7,7 @@
 import {PlainObject} from '@xh/hoist/core';
 import {DashContainerModel} from '@xh/hoist/desktop/cmp/dash';
 import {serializeIcon} from '@xh/hoist/icon';
-import {throwIf} from '@xh/hoist/utils/js';
+import {logDebug, throwIf} from '@xh/hoist/utils/js';
 import {isArray, isEmpty, isFinite, isNil, isPlainObject, isString, round} from 'lodash';
 import {DashContainerViewSpec} from '../DashContainerViewSpec';
 import GoldenLayout, {ContentItem} from 'golden-layout';
@@ -119,8 +119,9 @@ function convertStateToGLInner(items = [], viewSpecs = [], containerSize, contai
             const viewSpec = viewSpecs.find(v => v.id === item.id);
 
             if (!viewSpec) {
-                console.debug(
-                    `Attempted to load non-existent or omitted view from state: ${item.id}`
+                logDebug(
+                    `Attempted to load non-existent or omitted view from state: ${item.id}`,
+                    'DashContainer'
                 );
                 return null;
             }

package/desktop/cmp/rest/RestGrid.ts

@@ -10,8 +10,10 @@ import {fragment} from '@xh/hoist/cmp/layout';
 import {hoistCmp, HoistProps, PlainObject, Some, uses} from '@xh/hoist/core';
 import {MaskProps} from '@xh/hoist/cmp/mask';
 import {panel, PanelProps} from '@xh/hoist/desktop/cmp/panel';
+import {toolbar} from '@xh/hoist/desktop/cmp/toolbar';
 import '@xh/hoist/desktop/register';
 import {getTestId} from '@xh/hoist/utils/js';
+import {isArray} from 'lodash';
 import {cloneElement, isValidElement, ReactElement, ReactNode} from 'react';
 
 import {restForm} from './impl/RestForm';
@@ -23,23 +25,33 @@ export interface RestGridProps
         Omit<PanelProps, 'model' | 'modelConfig' | 'modelRef'> {
     /**
      * This constitutes an 'escape hatch' for applications that need to get to the underlying
-     * ag-Grid API.  It should be used with care. Settings made here might be overwritten and/or
-     * interfere with the implementation of this component and its use of the ag-Grid API.
+     * AG Grid API. Use with care - settings made here might be overwritten and/or interfere with
+     * the implementation of this component and its use of AG Grid.
      */
     agOptions?: PlainObject;
 
-    /** Optional components rendered adjacent to the top toolbar's action buttons */
+    /**
+     * Optional components rendered adjacent to the top toolbar's action buttons.
+     * See also {@link tbar} to take full control of the toolbar.
+     */
     extraToolbarItems?: Some<ReactNode> | (() => Some<ReactNode>);
 
+    /** Classname to be passed to RestForm. */
+    formClassName?: string;
+
     /**
-     * Mask to render on this Component. Defaults to true, which renders a standard
-     * Hoist mask. Also can be set to false for no mask, or passed an element
-     * specifying a Mask instance.
+     * Mask to render on this Component. Defaults to true, which renders a standard Hoist mask.
+     * Set to null/false for no mask, or pass a fully customized mask element.
      */
     mask?: ReactElement | boolean;
 
-    /** Classname to be passed to RestForm. */
-    formClassName?: string;
+    /**
+     * A custom toolbar to be docked above the grid. Note that this supersedes the default
+     * toolbar, meaning the `extraToolbarItems` prop will be ignored, as will the `RestGridModel`
+     * configs `toolbarActions`, `filterFields`, and `showRefreshButton`. If specified as an array,
+     * will be passed as children to a Toolbar component.
+     */
+    tbar?: Some<ReactNode>;
 }
 
 export const [RestGrid, restGrid] = hoistCmp.withFactory<RestGridProps>({
@@ -51,6 +63,7 @@ export const [RestGrid, restGrid] = hoistCmp.withFactory<RestGridProps>({
         const {
                 model,
                 extraToolbarItems,
+                tbar,
                 mask = true,
                 agOptions,
                 formClassName,
@@ -63,7 +76,7 @@ export const [RestGrid, restGrid] = hoistCmp.withFactory<RestGridProps>({
             panel({
                 ref,
                 ...restProps,
-                tbar: restGridToolbar({model, extraToolbarItems, testId}),
+                tbar: innerToolbar({model, tbar, extraToolbarItems, testId}),
                 item: grid({model: gridModel, agOptions, testId: getTestId(testId, 'grid')}),
                 mask: getMaskFromProp(model, mask)
             }),
@@ -76,6 +89,14 @@ export const [RestGrid, restGrid] = hoistCmp.withFactory<RestGridProps>({
     }
 });
 
+const innerToolbar = hoistCmp.factory({
+    render({model, tbar, extraToolbarItems, testId}) {
+        if (isArray(tbar)) return toolbar(tbar);
+        if (tbar) return tbar;
+        return restGridToolbar({model, extraToolbarItems, testId});
+    }
+});
+
 function getMaskFromProp(model, mask) {
     if (isValidElement(mask)) {
         mask = cloneElement<MaskProps>(mask, {bind: model.loadModel});

package/inspector/instances/InstancesModel.ts

@@ -130,7 +130,7 @@ export class InstancesModel extends HoistModel {
             instance = this.getInstance(xhId);
 
         if (!instance) {
-            console.warn(`Instance with xhId ${xhId} no longer alive - cannot be logged`);
+            this.logWarn(`Instance with xhId ${xhId} no longer alive - cannot be logged`);
         } else {
             console.log(`[${xhId}]`, instance);
             XH.toast({
@@ -147,7 +147,7 @@ export class InstancesModel extends HoistModel {
             instance = this.getInstance(instanceXhId);
 
         if (!instance) {
-            console.warn(`Instance ${instanceDisplayName} no longer alive - cannot be logged`);
+            this.logWarn(`Instance ${instanceDisplayName} no longer alive - cannot be logged`);
         } else {
             console.log(`[${instanceDisplayName}].${property}`, instance[property]);
             XH.toast({

package/kit/ag-grid/index.ts

@@ -5,7 +5,7 @@
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
 
-import {checkVersion} from '@xh/hoist/utils/js/VersionUtils';
+import {checkVersion, logError} from '@xh/hoist/utils/js';
 
 /**
  * The exports below are ag-Grid components provided at runtime by applications.
@@ -57,7 +57,7 @@ const MAX_VERSION = '31.*.*';
  */
 export function installAgGrid(ComponentReactWrapper, version: string) {
     if (!checkVersion(version, MIN_VERSION, MAX_VERSION)) {
-        console.error(
+        logError(
             `This version of Hoist requires an ag-Grid version between ${MIN_VERSION} and ` +
                 `${MAX_VERSION}. Version ${version} detected. ag-Grid will be unavailable.`
         );

package/kit/highcharts/index.ts

@@ -5,7 +5,7 @@
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
 
-import {checkVersion} from '@xh/hoist/utils/js/VersionUtils';
+import {checkVersion, logError} from '@xh/hoist/utils/js';
 
 export let Highcharts = null;
 
@@ -19,7 +19,7 @@ const MAX_VERSION = '11.*.*';
 export function installHighcharts(HighchartsImpl) {
     const {version} = HighchartsImpl;
     if (!checkVersion(version, MIN_VERSION, MAX_VERSION)) {
-        console.error(
+        logError(
             `This version of Hoist requires a Highcharts version between ${MIN_VERSION} and ` +
                 `${MAX_VERSION}. Version ${version} detected. Highcharts will be unavailable.`
         );

package/package.json

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

package/promise/Promise.ts

@@ -305,16 +305,3 @@ const enhancePromise = promisePrototype => {
 
 // Enhance canonical Promises.
 enhancePromise(Promise.prototype);
-
-// MS Edge returns a "native Promise" from async functions that won't get the enhancements above.
-// Check to see if we're in such an environment and enhance that prototype as well.
-// @see https://github.com/xh/hoist-react/issues/1411
-const asyncFnReturn = (async () => {})();
-if (!(asyncFnReturn instanceof Promise)) {
-    console.debug(
-        '"Native" Promise return detected as return from async function - enhancing prototype'
-    );
-
-    // @ts-ignore
-    enhancePromise(asyncFnReturn.__proto__);
-}

package/svc/FetchService.ts

@@ -261,7 +261,7 @@ export class FetchService extends HoistService {
         const {correlationIdHeaderKey} = this;
         if (opts.correlationId) {
             if (headers[correlationIdHeaderKey]) {
-                console.warn(
+                this.logWarn(
                     `Header ${correlationIdHeaderKey} value already set within FetchOptions.`
                 );
             } else {