@xh/hoist 72.2.0 → 72.3.0

package/build/types/svc/TrackService.d.ts

@@ -6,15 +6,45 @@ import { HoistService, TrackOptions } from '@xh/hoist/core';
  */
 export declare class TrackService extends HoistService {
     static instance: TrackService;
+    private clientHealthReportSources;
     private oncePerSessionSent;
     private pending;
     initAsync(): Promise<void>;
-    get conf(): any;
+    get conf(): ActivityTrackingConfig;
     get enabled(): boolean;
     /** Track User Activity. */
     track(options: TrackOptions | string): void;
+    /**
+     * Register a new source for client health report data. No-op if background health report is
+     * not generally enabled via `xhActivityTrackingConfig.clientHealthReport.intervalMins`.
+     *
+     * @param key - key under which to report the data - can be used to remove this source later.
+     * @param callback - function returning serializable to include with each report.
+     */
+    addClientHealthReportSource(key: string, callback: () => any): void;
+    /** Unregister a previously-enabled source for client health report data. */
+    removeClientHealthReportSource(key: string): void;
     private pushPendingAsync;
     private pushPendingBuffered;
     private toServerJson;
     private logMessage;
+    private sendClientHealthReport;
 }
+interface ActivityTrackingConfig {
+    clientHealthReport?: Partial<TrackOptions> & {
+        intervalMins: number;
+    };
+    enabled: boolean;
+    logData: boolean;
+    maxDataLength: number;
+    maxRows?: {
+        default: number;
+        options: number[];
+    };
+    levels?: Array<{
+        username: string | '*';
+        category: string | '*';
+        severity: 'DEBUG' | 'INFO' | 'WARN';
+    }>;
+}
+export {};

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

@@ -1,4 +1,41 @@
 /**
  * Extract information (if available) about the client browser's window, screen, and network speed.
  */
-export declare function getClientDeviceInfo(): any;
+export declare function getClientDeviceInfo(): ClientDeviceInfo;
+export interface ClientDeviceInfo {
+    window: {
+        devicePixelRatio: number;
+        screenX: number;
+        screenY: number;
+        innerWidth: number;
+        innerHeight: number;
+        outerWidth: number;
+        outerHeight: number;
+    };
+    screen?: {
+        availWidth: number;
+        availHeight: number;
+        width: number;
+        height: number;
+        colorDepth: number;
+        pixelDepth: number;
+        availLeft: number;
+        availTop: number;
+        orientation?: {
+            angle: number;
+            type: string;
+        };
+    };
+    connection?: {
+        downlink: number;
+        effectiveType: string;
+        rtt: number;
+    };
+    memory: {
+        modelCount: number;
+        usedPctLimit?: number;
+        jsHeapSizeLimit?: number;
+        totalJSHeapSize?: number;
+        usedJSHeapSize?: number;
+    };
+}

package/data/Store.ts

@@ -18,6 +18,7 @@ import {
     isEmpty,
     isFunction,
     isNil,
+    isNull,
     isString,
     values,
     remove as lodashRemove,
@@ -692,6 +693,8 @@ export class Store extends HoistBase {
      * for backwards compat with app code predating support for multiple {@link summaryRecords}.
      */
     get summaryRecord(): StoreRecord {
+        if (isNull(this.summaryRecords)) return null;
+
         throwIf(
             this.summaryRecords.length > 1,
             'Store has multiple summary records - must access via Store.summaryRecords.'

package/desktop/cmp/grid/editors/BooleanEditor.ts

@@ -49,11 +49,23 @@ export const [BooleanEditor, booleanEditor] = hoistCmp.withFactory<BooleanEditor
     }
 });
 
-function useInstantEditor({onValueChange, initialValue, stopEditing}: CustomCellEditorProps, ref) {
+function useInstantEditor(
+    {onValueChange, initialValue, stopEditing, eventKey, eGridCell}: CustomCellEditorProps,
+    ref
+) {
+    // Don't toggle if the user has tabbed into the editor. See https://github.com/xh/hoist-react/issues/3943.
+    // Fortunately, `eventKey` is null for tab, so we can use that to accept other keyboard events.
+    // Unfortunately, it is also null for mouse events, so we check if the grid cell is currently
+    // underneath the mouse position via `:hover` selector.
     useEffect(() => {
-        onValueChange(!initialValue);
+        const els = document.querySelectorAll(':hover'),
+            topEl = els[els.length - 1];
+
+        if (eventKey || topEl === eGridCell) {
+            onValueChange(!initialValue);
+        }
         stopEditing();
-    }, [stopEditing, initialValue, onValueChange]);
+    }, [stopEditing, initialValue, onValueChange, eventKey, eGridCell]);
 
     return null;
 }

package/desktop/cmp/tab/TabSwitcher.ts

@@ -41,7 +41,7 @@ import {CSSProperties, ReactElement, KeyboardEvent} from 'react';
  *
  * Overflowing tabs can be displayed in a dropdown menu if `enableOverflow` is true.
  * Note that in order for tabs to overflow, the TabSwitcher or it's wrapper must have a
- * a maximum width.
+ * maximum width.
  */
 export const [TabSwitcher, tabSwitcher] = hoistCmp.withFactory<TabSwitcherProps>({
     displayName: 'TabSwitcher',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xh/hoist",
-  "version": "72.2.0",
+  "version": "72.3.0",
   "description": "Hoist add-on for building and deploying React Applications.",
   "repository": "github:xh/hoist-react",
   "homepage": "https://xh.io",
@@ -30,7 +30,7 @@
   },
   "dependencies": {
     "@auth0/auth0-spa-js": "~2.1.3",
-    "@azure/msal-browser": "~3.28.0",
+    "@azure/msal-browser": "~4.8.0",
     "@blueprintjs/core": "^5.10.5",
     "@blueprintjs/datetime": "^5.3.7",
     "@blueprintjs/datetime2": "^2.3.7",

package/security/BaseOAuthClient.ts

@@ -64,14 +64,13 @@ export interface BaseOAuthClientConfig<S extends AccessTokenSpec> {
     idScopes?: string[];
 
     /**
-     * Optional map of access tokens to be loaded and maintained.
+     * Optional spec for access tokens to be loaded and maintained to support access to one or more
+     * different back-end resources, distinct from the core Hoist auth flow via ID token.
      *
-     * Map of code to a spec for an access token.  The code is app-determined and
-     * will simply be used to get the loaded token via tha getAccessToken() method. The
-     * spec is implementation specific, but will typically include scopes to be loaded
-     * for the access token and potentially other meta-data required by the underlying provider.
-     *
-     * Use this map to gain targeted access tokens for different back-end resources.
+     * Map of key to a spec for an access token. The key is an arbitrary, app-determined string
+     * used to retrieve the loaded token via {@link getAccessTokenAsync}. The spec is implementation
+     * specific, but will typically include scopes to be loaded for the access token and potentially
+     * other metadata required by the underlying provider.
      */
     accessTokens?: Record<string, S>;
 }
@@ -120,7 +119,7 @@ export abstract class BaseOAuthClient<
         throwIf(!config.clientId, 'Missing OAuth clientId. Please review your configuration.');
 
         this.idScopes = union(['openid', 'email'], config.idScopes);
-        this.accessSpecs = this.config.accessTokens;
+        this.accessSpecs = this.config.accessTokens ?? {};
     }
 
     /**
@@ -164,7 +163,10 @@ export abstract class BaseOAuthClient<
      * Get an Access token.
      */
     async getAccessTokenAsync(key: string): Promise<Token> {
-        return this.fetchAccessTokenAsync(this.accessSpecs[key], true);
+        const spec = this.accessSpecs[key];
+        if (!spec) throw XH.exception(`No access token spec configured for key "${key}"`);
+
+        return this.fetchAccessTokenAsync(spec, true);
     }
 
     /**
@@ -314,7 +316,7 @@ export abstract class BaseOAuthClient<
         const eagerOnly = opts?.eagerOnly ?? false,
             useCache = opts?.useCache ?? true,
             accessSpecs = eagerOnly
-                ? pickBy(this.accessSpecs, spec => spec.fetchMode === 'eager')
+                ? pickBy(this.accessSpecs, spec => spec.fetchMode !== 'lazy') // specs are eager by default - opt-in to lazy
                 : this.accessSpecs,
             ret: TokenMap = {};
 

package/security/Types.ts

@@ -7,16 +7,45 @@
 
 import {Token} from './Token';
 
-export type TokenMap = Record<string, Token>;
-
 export interface AccessTokenSpec {
     /**
-     * Mode governing when the access token should be requested from provider.
-     *      eager (default) - initiate lookup on initialization, but do not block on failure.
-     *      lazy - lookup when requested by client.
+     * Mode governing when the access token should be requested from provider:
+     *      - eager (or undefined) - load on overall initialization, but do not block on failure.
+     *        Useful for tokens that an app is almost certain to require during a user session.
+     *      - lazy - defer loading until first requested by client. Useful for tokens that might
+     *        never be needed by the app during a given user session.
      */
-    fetchMode: 'eager' | 'lazy';
+    fetchMode?: 'eager' | 'lazy';
 
     /** Scopes for the desired access token.*/
     scopes: string[];
 }
+
+export type TokenMap = Record<string, Token>;
+
+/** Aggregated telemetry results, produced by {@link MsalClient} when enabled via config. */
+export interface TelemetryResults {
+    /** Stats by event type - */
+    events: Record<string, TelemetryEventResults>;
+}
+
+/** Aggregated telemetry results for a single type of event. */
+export interface TelemetryEventResults {
+    firstTime: Date;
+    lastTime: Date;
+    successCount: number;
+    failureCount: number;
+    /** Timing info (in ms) for event instances reported with duration. */
+    duration: {
+        count: number;
+        total: number;
+        average: number;
+        worst: number;
+    };
+    lastFailure?: {
+        time: Date;
+        duration: number;
+        code: string;
+        name: string;
+    };
+}

package/security/msal/MsalClient.ts

@@ -7,6 +7,8 @@
 import * as msal from '@azure/msal-browser';
 import {
     AccountInfo,
+    BrowserPerformanceClient,
+    Configuration,
     IPublicClientApplication,
     LogLevel,
     PopupRequest,
@@ -14,10 +16,10 @@ import {
 } from '@azure/msal-browser';
 import {XH} from '@xh/hoist/core';
 import {Token} from '@xh/hoist/security/Token';
-import {AccessTokenSpec, TokenMap} from '../Types';
 import {logDebug, logError, logInfo, logWarn, mergeDeep, throwIf} from '@xh/hoist/utils/js';
 import {flatMap, union, uniq} from 'lodash';
 import {BaseOAuthClient, BaseOAuthClientConfig} from '../BaseOAuthClient';
+import {AccessTokenSpec, TelemetryResults, TokenMap} from '../Types';
 
 export interface MsalClientConfig extends BaseOAuthClientConfig<MsalTokenSpec> {
     /**
@@ -34,6 +36,13 @@ export interface MsalClientConfig extends BaseOAuthClientConfig<MsalTokenSpec> {
      */
     domainHint?: string;
 
+    /**
+     * True to enable support for built-in telemetry provided by this class's internal MSAL client.
+     * Captured performance events will be summarized via {@link telemetryResults}.
+     * See https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/performance.md
+     */
+    enableTelemetry?: boolean;
+
     /**
      * If specified, the client will use this value when initializing the app to enforce a minimum
      * amount of time during which no further auth flow with the provider should be necessary.
@@ -104,6 +113,10 @@ export class MsalClient extends BaseOAuthClient<MsalClientConfig, MsalTokenSpec>
     private account: AccountInfo; // Authenticated account
     private initialTokenLoad: boolean;
 
+    /** Enable telemetry via `enableTelemetry` ctor config, or via {@link enableTelemetry}. */
+    telemetryResults: TelemetryResults = {events: {}};
+    private _telemetryCbHandle: string = null;
+
     constructor(config: MsalClientConfig) {
         super({
             initRefreshTokenExpirationOffsetSecs: -1,
@@ -118,6 +131,9 @@ export class MsalClient extends BaseOAuthClient<MsalClientConfig, MsalTokenSpec>
     //-------------------------------------------
     protected override async doInitAsync(): Promise<TokenMap> {
         const client = (this.client = await this.createClientAsync());
+        if (this.config.enableTelemetry) {
+            this.enableTelemetry();
+        }
 
         // 0) Handle redirect return
         const redirectResp = await client.handleRedirectPromise();
@@ -247,6 +263,86 @@ export class MsalClient extends BaseOAuthClient<MsalClientConfig, MsalTokenSpec>
             : await client.logoutPopup(opts);
     }
 
+    //------------------------
+    // Telemetry
+    //------------------------
+    enableTelemetry(): void {
+        if (this._telemetryCbHandle) {
+            this.logInfo('Telemetry already enabled', this.telemetryResults);
+            return;
+        }
+
+        this.telemetryResults = {events: {}};
+
+        this._telemetryCbHandle = this.client.addPerformanceCallback(events => {
+            events.forEach(e => {
+                try {
+                    const {events} = this.telemetryResults,
+                        {name, startTimeMs, durationMs, success, errorName, errorCode} = e,
+                        eTime = startTimeMs ? new Date(startTimeMs) : new Date();
+
+                    const eResult = (events[name] ??= {
+                        firstTime: eTime,
+                        lastTime: eTime,
+                        successCount: 0,
+                        failureCount: 0,
+                        duration: {count: 0, total: 0, average: 0, worst: 0},
+                        lastFailure: null
+                    });
+                    eResult.lastTime = eTime;
+
+                    if (success) {
+                        eResult.successCount++;
+                    } else {
+                        eResult.failureCount++;
+                        eResult.lastFailure = {
+                            time: eTime,
+                            duration: e.durationMs,
+                            code: errorCode,
+                            name: errorName
+                        };
+                    }
+
+                    if (durationMs) {
+                        const {duration} = eResult;
+                        duration.count++;
+                        duration.total += durationMs;
+                        duration.average = Math.round(duration.total / duration.count);
+                        duration.worst = Math.max(duration.worst, durationMs);
+                    }
+                } catch (e) {
+                    this.logError(`Error processing telemetry event`, e);
+                }
+            });
+        });
+
+        // Ask TrackService to include in background health check report, if enabled on that service.
+        // Handle TrackService not yet initialized (common, this client likely initialized before.)
+        this.addReaction({
+            when: () => XH.appIsRunning,
+            run: () =>
+                XH.trackService.addClientHealthReportSource(
+                    'msalClient',
+                    () => this.telemetryResults
+                )
+        });
+
+        this.logInfo('Telemetry enabled');
+    }
+
+    disableTelemetry(): void {
+        if (!this._telemetryCbHandle) {
+            this.logInfo('Telemetry already disabled');
+            return;
+        }
+
+        this.client.removePerformanceCallback(this._telemetryCbHandle);
+        this._telemetryCbHandle = null;
+
+        XH.trackService.removeClientHealthReportSource('msalClient');
+        this.logInfo('Telemetry disabled', this.telemetryResults);
+    }
+
     //------------------------
     // Private implementation
     //------------------------
@@ -263,29 +359,38 @@ export class MsalClient extends BaseOAuthClient<MsalClientConfig, MsalTokenSpec>
     }
 
     private async createClientAsync(): Promise<IPublicClientApplication> {
-        const {clientId, authority, msalLogLevel, msalClientOptions} = this.config;
+        const {clientId, authority, msalLogLevel, msalClientOptions, enableTelemetry} = this.config;
         throwIf(!authority, 'Missing MSAL authority. Please review your configuration.');
 
-        return msal.PublicClientApplication.createPublicClientApplication(
-            mergeDeep(
-                {
-                    auth: {
-                        clientId,
-                        authority,
-                        postLogoutRedirectUri: this.postLogoutRedirectUrl
-                    },
-                    system: {
-                        loggerOptions: {
-                            loggerCallback: this.logFromMsal,
-                            logLevel: msalLogLevel
-                        }
-                    },
-                    cache: {
-                        cacheLocation: 'localStorage' // allows sharing auth info across tabs.
+        const mergedConf: Configuration = mergeDeep(
+            {
+                auth: {
+                    clientId,
+                    authority,
+                    postLogoutRedirectUri: this.postLogoutRedirectUrl
+                },
+                system: {
+                    loggerOptions: {
+                        loggerCallback: this.logFromMsal,
+                        logLevel: msalLogLevel
                     }
                 },
-                msalClientOptions
-            )
+                cache: {
+                    cacheLocation: 'localStorage' // allows sharing auth info across tabs.
+                }
+            },
+            msalClientOptions
+        );
+
+        return msal.PublicClientApplication.createPublicClientApplication(
+            enableTelemetry
+                ? {
+                      ...mergedConf,
+                      telemetry: {
+                          client: new BrowserPerformanceClient(mergedConf)
+                      }
+                  }
+                : mergedConf
         );
     }
 

package/svc/FetchService.ts

@@ -217,8 +217,9 @@ export class FetchService extends HoistService {
     //-----------------------
     private async fetchInternalAsync(opts: FetchOptions): Promise<any> {
         opts = this.withCorrelationId(opts);
-        opts = await this.withDefaultHeadersAsync(opts);
-        let ret = this.managedFetchAsync(opts);
+
+        // Core Promise - chained with custom headers callback to ensure that work is included in overall tracked time.
+        let ret = this.withDefaultHeadersAsync(opts).then(opts => this.managedFetchAsync(opts));
 
         // Apply tracking
         const {correlationId, loadSpec, track} = opts;

package/svc/TrackService.ts

@@ -5,10 +5,11 @@
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
 import {HoistService, PlainObject, TrackOptions, XH} from '@xh/hoist/core';
-import {SECONDS} from '@xh/hoist/utils/datetime';
+import {Timer} from '@xh/hoist/utils/async';
+import {MINUTES, SECONDS} from '@xh/hoist/utils/datetime';
 import {isOmitted} from '@xh/hoist/utils/impl';
-import {debounced, stripTags, withDefault} from '@xh/hoist/utils/js';
-import {isEmpty, isNil, isString} from 'lodash';
+import {debounced, getClientDeviceInfo, stripTags, withDefault} from '@xh/hoist/utils/js';
+import {isEmpty, isNil, isString, round} from 'lodash';
 
 /**
  * Primary service for tracking any activity that an application's admins want to track.
@@ -18,23 +19,38 @@ import {isEmpty, isNil, isString} from 'lodash';
 export class TrackService extends HoistService {
     static instance: TrackService;
 
+    private clientHealthReportSources: Map<string, () => any> = new Map();
     private oncePerSessionSent = new Map();
     private pending: PlainObject[] = [];
 
     override async initAsync() {
+        const {clientHealthReport} = this.conf;
+        if (clientHealthReport?.intervalMins > 0) {
+            Timer.create({
+                runFn: () => this.sendClientHealthReport(),
+                interval: clientHealthReport.intervalMins,
+                intervalUnits: MINUTES,
+                delay: true
+            });
+        }
+
         window.addEventListener('beforeunload', () => this.pushPendingAsync());
     }
 
-    get conf() {
-        return XH.getConf('xhActivityTrackingConfig', {
+    get conf(): ActivityTrackingConfig {
+        const appConfig = XH.getConf('xhActivityTrackingConfig', {});
+        return {
+            clientHealthReport: {intervalMins: -1},
             enabled: true,
+            logData: false,
             maxDataLength: 2000,
             maxRows: {
                 default: 10000,
                 options: [1000, 5000, 10000, 25000]
             },
-            logData: false
-        });
+            levels: [{username: '*', category: '*', severity: 'INFO'}],
+            ...appConfig
+        };
     }
 
     get enabled(): boolean {
@@ -79,13 +95,29 @@ export class TrackService extends HoistService {
             sent.set(key, true);
         }
 
-        // Otherwise - log and for next batch,
+        // Otherwise - log and queue to send with next debounced push to server.
         this.logMessage(options);
 
         this.pending.push(this.toServerJson(options));
         this.pushPendingBuffered();
     }
 
+    /**
+     * Register a new source for client health report data. No-op if background health report is
+     * not generally enabled via `xhActivityTrackingConfig.clientHealthReport.intervalMins`.
+     *
+     * @param key - key under which to report the data - can be used to remove this source later.
+     * @param callback - function returning serializable to include with each report.
+     */
+    addClientHealthReportSource(key: string, callback: () => any) {
+        this.clientHealthReportSources.set(key, callback);
+    }
+
+    /** Unregister a previously-enabled source for client health report data. */
+    removeClientHealthReportSource(key: string) {
+        this.clientHealthReportSources.delete(key);
+    }
+
     //------------------
     // Implementation
     //------------------
@@ -144,4 +176,58 @@ export class TrackService extends HoistService {
 
         this.logInfo(...consoleMsgs);
     }
+
+    private sendClientHealthReport() {
+        const {
+                intervalMins,
+                severity: defaultSeverity,
+                ...rest
+            } = this.conf.clientHealthReport ?? {},
+            {loadStarted} = XH.appContainerModel.appStateModel;
+
+        const data = {
+            session: {
+                started: loadStarted,
+                durationMins: round((Date.now() - loadStarted) / 60_000, 1)
+            },
+            ...getClientDeviceInfo()
+        };
+
+        let severity = defaultSeverity ?? 'INFO';
+        this.clientHealthReportSources.forEach((cb, k) => {
+            try {
+                data[k] = cb();
+                if (data[k]?.severity === 'WARN') severity = 'WARN';
+            } catch (e) {
+                data[k] = `Error: ${e.message}`;
+                this.logWarn(`Error running client health report callback for [${k}]`, e);
+            }
+        });
+
+        this.track({
+            category: 'App',
+            message: 'Submitted health report',
+            severity,
+            ...rest,
+            data
+        });
+    }
+}
+
+interface ActivityTrackingConfig {
+    clientHealthReport?: Partial<TrackOptions> & {
+        intervalMins: number;
+    };
+    enabled: boolean;
+    logData: boolean;
+    maxDataLength: number;
+    maxRows?: {
+        default: number;
+        options: number[];
+    };
+    levels?: Array<{
+        username: string | '*';
+        category: string | '*';
+        severity: 'DEBUG' | 'INFO' | 'WARN';
+    }>;
 }

package/svc/WebSocketService.ts

@@ -282,8 +282,7 @@ export class WebSocketService extends HoistService {
 
     buildWebSocketUrl() {
         const protocol = window.location.protocol == 'https:' ? 'wss:' : 'ws:',
-            endpoint = 'xhWebSocket';
-
+            endpoint = 'xhWebSocket?clientAppVersion=' + XH.appVersion;
         return XH.isDevelopmentMode
             ? `${protocol}//${XH.baseUrl.split('//')[1]}${endpoint}`
             : `${protocol}//${window.location.host}${XH.baseUrl}${endpoint}`;