@xh/hoist 72.4.0 → 72.5.0

package/CHANGELOG.md

@@ -1,14 +1,26 @@
 # Changelog
 
+## v72.5.0 - 2025-04-14
+
+### 🎁 New Features
+
+* Added option from the Admin Console > Websockets tab to request a client health report from any
+  connected clients.
+* Enabled telemetry reporting from `WebSocketService`.
+* Updated `MenuItem.actionFn()` to receive the click event as an additional argument.
+* Support for reporting App Build, Tab Id, and Load Id in websocket admin page.
+
 ## v72.4.0 - 2025-04-09
 
 ### 🎁 New Features
-* New methods for formatting timestamps within nested JSON objects.  See `withFormattedTimestamps`
+
+* Added new methods for formatting timestamps within JSON objects. See `withFormattedTimestamps`
   and `timestampReplacer` in the `@xh/hoist/format` package.
-* `ViewManagerConfig` takes new optional key `viewMenuItemFn` to allow ViewManager implementations
-  to customize the menu items for views in the view manager menu.
+* Added new `ViewManagerConfig.viewMenuItemFn` option to support custom rendering of pinned views in
+  the drop-down menu.
 
 ### ⚙️ Technical
+
 * Added dedicated `ClientHealthService` for managing client health report. Additional enhancements
   to health report to include information about web sockets, idle time, and page state.
 
@@ -28,11 +40,6 @@
 
 * Improved fetch request tracking to include time spent loading headers as specified by application.
 
-### ⚙️ Technical
-
-* Update shape of returned `BrowserUtils.getClientDeviceInfo()` to nest several properties under new
-  top-level `window` key and report JS heap size / usage values under the `memory` block in MB.
-
 ### 📚 Libraries
 
 * @azure/msal-browser `3.28 → 4.8.0`

package/admin/tabs/activity/tracking/ActivityTrackingModel.ts

@@ -5,17 +5,17 @@
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
 import {exportFilename} from '@xh/hoist/admin/AdminUtils';
-import {GroupingChooserModel} from '@xh/hoist/cmp/grouping';
+import * as Col from '@xh/hoist/admin/columns';
 import {FilterChooserModel} from '@xh/hoist/cmp/filter';
 import {FormModel} from '@xh/hoist/cmp/form';
 import {GridModel, TreeStyle} from '@xh/hoist/cmp/grid';
+import {GroupingChooserModel} from '@xh/hoist/cmp/grouping';
 import {HoistModel, LoadSpec, managed, XH} from '@xh/hoist/core';
 import {Cube, CubeFieldSpec, FieldSpec} from '@xh/hoist/data';
 import {fmtNumber} from '@xh/hoist/format';
 import {action, computed, makeObservable} from '@xh/hoist/mobx';
 import {LocalDate} from '@xh/hoist/utils/datetime';
-import * as Col from '@xh/hoist/admin/columns';
-import {isEmpty, round} from 'lodash';
+import {compact, isEmpty, round} from 'lodash';
 import moment from 'moment';
 
 export const PERSIST_ACTIVITY = {localStorageKey: 'xhAdminActivityState'};
@@ -109,14 +109,13 @@ export class ActivityTrackingModel extends HoistModel {
             ] as CubeFieldSpec[]
         });
 
-        const enableValues = true;
         this.filterChooserModel = new FilterChooserModel({
             fieldSpecs: [
-                {field: 'category', enableValues},
+                {field: 'category'},
                 {field: 'correlationId'},
-                {field: 'username', displayName: 'User', enableValues},
-                {field: 'device', enableValues},
-                {field: 'browser', enableValues},
+                {field: 'username', displayName: 'User'},
+                {field: 'device'},
+                {field: 'browser'},
                 {
                     field: 'elapsed',
                     valueRenderer: v => {
@@ -330,12 +329,21 @@ export class ActivityTrackingModel extends HoistModel {
     }
 
     private async loadLookupsAsync() {
-        const lookups = await XH.fetchJson({url: 'trackLogAdmin/lookups'});
-
-        this.filterChooserModel.fieldSpecs.forEach(spec => {
-            const {field} = spec;
-            if (lookups[field]) spec.values = lookups[field];
-        });
+        try {
+            const lookups = await XH.fetchJson({url: 'trackLogAdmin/lookups'});
+            this.filterChooserModel.fieldSpecs.forEach(spec => {
+                const {field} = spec,
+                    lookup = lookups[field] ? compact(lookups[field]) : null;
+
+                if (!isEmpty(lookup)) {
+                    spec.values = lookup;
+                    spec.enableValues = true;
+                    spec.hasExplicitValues = true;
+                }
+            });
+        } catch (e) {
+            XH.handleException(e, {title: 'Error loading lookups for filtering'});
+        }
     }
 
     @computed

package/admin/tabs/cluster/instances/websocket/WebSocketColumns.ts

@@ -73,11 +73,33 @@ export const lastReceivedTime: ColumnSpec = {
     width: 140
 };
 
-export const clientAppVersion: ColumnSpec = {
+export const appVersion: ColumnSpec = {
     field: {
-        name: 'clientAppVersion',
+        name: 'appVersion',
         type: 'string',
         displayName: 'Client Version'
     },
     width: 120
 };
+
+export const appBuild: ColumnSpec = {
+    field: {
+        name: 'appBuild',
+        type: 'string'
+    },
+    width: 120
+};
+export const loadId: ColumnSpec = {
+    field: {
+        name: 'loadId',
+        type: 'string'
+    },
+    width: 120
+};
+export const tabId: ColumnSpec = {
+    field: {
+        name: 'tabId',
+        type: 'string'
+    },
+    width: 120
+};

package/admin/tabs/cluster/instances/websocket/WebSocketModel.ts

@@ -5,20 +5,21 @@
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
 import {exportFilenameWithDate} from '@xh/hoist/admin/AdminUtils';
+import {AppModel} from '@xh/hoist/admin/AppModel';
 import * as Col from '@xh/hoist/admin/columns';
 import {BaseInstanceModel} from '@xh/hoist/admin/tabs/cluster/instances/BaseInstanceModel';
 import {GridModel} from '@xh/hoist/cmp/grid';
 import {div, p} from '@xh/hoist/cmp/layout';
 import {LoadSpec, managed, XH} from '@xh/hoist/core';
+import {RecordActionSpec, StoreRecord} from '@xh/hoist/data';
 import {textInput} from '@xh/hoist/desktop/cmp/input';
 import {Icon} from '@xh/hoist/icon';
 import {makeObservable, observable, runInAction} from '@xh/hoist/mobx';
 import {Timer} from '@xh/hoist/utils/async';
 import {SECONDS} from '@xh/hoist/utils/datetime';
+import {pluralize} from '@xh/hoist/utils/js';
 import {isEmpty} from 'lodash';
 import * as WSCol from './WebSocketColumns';
-import {RecordActionSpec} from '@xh/hoist/data';
-import {AppModel} from '@xh/hoist/admin/AppModel';
 
 export class WebSocketModel extends BaseInstanceModel {
     @observable
@@ -34,11 +35,19 @@ export class WebSocketModel extends BaseInstanceModel {
         text: 'Force suspend',
         icon: Icon.stopCircle(),
         intent: 'danger',
-        actionFn: () => this.forceSuspendAsync(),
+        actionFn: ({selectedRecords}) => this.forceSuspendAsync(selectedRecords),
         displayFn: () => ({hidden: AppModel.readonly}),
         recordsRequired: true
     };
 
+    reqHealthReportAction: RecordActionSpec = {
+        text: 'Request Health Report',
+        icon: Icon.health(),
+        actionFn: ({selectedRecords}) => this.requestHealthReportAsync(selectedRecords),
+        recordsRequired: true,
+        hidden: !XH.trackService.enabled
+    };
+
     constructor() {
         super();
         makeObservable(this);
@@ -48,7 +57,12 @@ export class WebSocketModel extends BaseInstanceModel {
             enableExport: true,
             exportOptions: {filename: exportFilenameWithDate('ws-connections')},
             selModel: 'multiple',
-            contextMenu: [this.forceSuspendAction, '-', ...GridModel.defaultContextMenu],
+            contextMenu: [
+                this.forceSuspendAction,
+                this.reqHealthReportAction,
+                '-',
+                ...GridModel.defaultContextMenu
+            ],
             store: {
                 idSpec: 'key',
                 processRawData: row => {
@@ -78,7 +92,10 @@ export class WebSocketModel extends BaseInstanceModel {
                 WSCol.lastSentTime,
                 WSCol.receivedMessageCount,
                 WSCol.lastReceivedTime,
-                WSCol.clientAppVersion
+                WSCol.appVersion,
+                WSCol.appBuild,
+                WSCol.loadId,
+                WSCol.tabId
             ]
         });
 
@@ -107,9 +124,8 @@ export class WebSocketModel extends BaseInstanceModel {
         }
     }
 
-    async forceSuspendAsync() {
-        const {selectedRecords} = this.gridModel;
-        if (isEmpty(selectedRecords)) return;
+    async forceSuspendAsync(toRecs: StoreRecord[]) {
+        if (isEmpty(toRecs)) return;
 
         const message = await XH.prompt<string>({
             title: 'Please confirm...',
@@ -123,7 +139,7 @@ export class WebSocketModel extends BaseInstanceModel {
             },
             message: div(
                 p(
-                    `This action will force ${selectedRecords.length} connected client(s) into suspended mode, halting all background refreshes and other activity, masking the UI, and requiring users to reload the app to continue.`
+                    `This action will force ${toRecs.length} connected client(s) into suspended mode, halting all background refreshes and other activity, masking the UI, and requiring users to reload the app to continue.`
                 ),
                 p('Enter an optional message below to display within the suspended app.')
             ),
@@ -134,23 +150,58 @@ export class WebSocketModel extends BaseInstanceModel {
         });
 
         if (message !== false) {
-            const tasks = selectedRecords.map(rec =>
-                XH.fetchJson({
-                    url: 'webSocketAdmin/pushToChannel',
-                    params: {
-                        channelKey: rec.data.key,
-                        topic: XH.webSocketService.FORCE_APP_SUSPEND_TOPIC,
-                        instance: this.instanceName,
-                        message
-                    }
-                })
-            );
-
-            await Promise.allSettled(tasks).track({
-                category: 'Audit',
-                message: 'Suspended clients via WebSocket',
-                data: {users: selectedRecords.map(it => it.data.user).sort()}
+            await this.bulkPush({
+                toRecs,
+                topic: XH.webSocketService.FORCE_APP_SUSPEND_TOPIC,
+                message,
+                trackMessage: 'Suspended clients via WebSocket'
             });
         }
     }
+
+    async requestHealthReportAsync(toRecs: StoreRecord[]) {
+        await this.bulkPush({
+            toRecs,
+            topic: XH.webSocketService.REQ_CLIENT_HEALTH_RPT_TOPIC
+        });
+        XH.successToast(
+            `Client health report requested for ${pluralize('client', toRecs.length, true)} - available in User Activity shortly...`
+        );
+    }
+
+    //------------------
+    // Implementation
+    //------------------
+    private async bulkPush({
+        toRecs,
+        topic,
+        message,
+        trackMessage
+    }: {
+        toRecs?: StoreRecord[];
+        topic: string;
+        message?: string;
+        trackMessage?: string;
+    }) {
+        if (isEmpty(toRecs)) return;
+
+        const tasks = toRecs.map(rec =>
+            XH.fetchJson({
+                url: 'webSocketAdmin/pushToChannel',
+                params: {
+                    channelKey: rec.data.key,
+                    instance: this.instanceName,
+                    topic,
+                    message
+                }
+            })
+        );
+
+        await Promise.allSettled(tasks).track({
+            category: 'Audit',
+            message: trackMessage,
+            data: {users: toRecs.map(it => it.data.user).sort()},
+            omit: !trackMessage
+        });
+    }
 }

package/admin/tabs/cluster/instances/websocket/WebSocketPanel.ts

@@ -16,7 +16,7 @@ import {panel} from '@xh/hoist/desktop/cmp/panel';
 import {recordActionBar} from '@xh/hoist/desktop/cmp/record';
 import {toolbarSep} from '@xh/hoist/desktop/cmp/toolbar';
 
-export const webSocketPanel = hoistCmp.factory({
+export const webSocketPanel = hoistCmp.factory<WebSocketModel>({
     model: creates(WebSocketModel),
 
     render({model}) {
@@ -26,7 +26,7 @@ export const webSocketPanel = hoistCmp.factory({
             bbar: [
                 recordActionBar({
                     selModel: model.gridModel.selModel,
-                    actions: [model.forceSuspendAction]
+                    actions: [model.forceSuspendAction, model.reqHealthReportAction]
                 }),
                 filler(),
                 relativeTimestamp({bind: 'lastRefresh', options: {prefix: 'Refreshed'}}),

package/appcontainer/AppStateModel.ts

@@ -92,14 +92,14 @@ export class AppStateModel extends HoistModel {
                     timestamp: loadStarted,
                     elapsed: Date.now() - loadStarted - (timings.LOGIN_REQUIRED ?? 0),
                     data: {
-                        clientId: XH.clientId,
-                        sessionId: XH.sessionId,
+                        loadId: XH.loadId,
+                        tabId: XH.tabId,
                         timings: mapKeys(timings, (v, k) => camelCase(k)),
                         clientHealth: XH.clientHealthService.getReport(),
                         window: this.getWindowData(),
                         screen: this.getScreenData()
                     },
-                    logData: ['clientId', 'sessionId'],
+                    logData: ['loadId', 'tabId'],
                     omit: !XH.appSpec.trackAppLoad
                 })
         });

package/build/types/admin/tabs/activity/tracking/ActivityTrackingModel.d.ts

@@ -1,7 +1,7 @@
-import { GroupingChooserModel } from '@xh/hoist/cmp/grouping';
 import { FilterChooserModel } from '@xh/hoist/cmp/filter';
 import { FormModel } from '@xh/hoist/cmp/form';
 import { GridModel } from '@xh/hoist/cmp/grid';
+import { GroupingChooserModel } from '@xh/hoist/cmp/grouping';
 import { HoistModel, LoadSpec } from '@xh/hoist/core';
 import { Cube } from '@xh/hoist/data';
 import { LocalDate } from '@xh/hoist/utils/datetime';

package/build/types/admin/tabs/cluster/instances/websocket/WebSocketColumns.d.ts

@@ -6,4 +6,7 @@ export declare const sentMessageCount: ColumnSpec;
 export declare const lastSentTime: ColumnSpec;
 export declare const receivedMessageCount: ColumnSpec;
 export declare const lastReceivedTime: ColumnSpec;
-export declare const clientAppVersion: ColumnSpec;
+export declare const appVersion: ColumnSpec;
+export declare const appBuild: ColumnSpec;
+export declare const loadId: ColumnSpec;
+export declare const tabId: ColumnSpec;

package/build/types/admin/tabs/cluster/instances/websocket/WebSocketModel.d.ts

@@ -1,13 +1,16 @@
 import { BaseInstanceModel } from '@xh/hoist/admin/tabs/cluster/instances/BaseInstanceModel';
 import { GridModel } from '@xh/hoist/cmp/grid';
 import { LoadSpec } from '@xh/hoist/core';
-import { RecordActionSpec } from '@xh/hoist/data';
+import { RecordActionSpec, StoreRecord } from '@xh/hoist/data';
 export declare class WebSocketModel extends BaseInstanceModel {
     lastRefresh: number;
     gridModel: GridModel;
     private _timer;
     forceSuspendAction: RecordActionSpec;
+    reqHealthReportAction: RecordActionSpec;
     constructor();
     doLoadAsync(loadSpec: LoadSpec): Promise<void>;
-    forceSuspendAsync(): Promise<void>;
+    forceSuspendAsync(toRecs: StoreRecord[]): Promise<void>;
+    requestHealthReportAsync(toRecs: StoreRecord[]): Promise<void>;
+    private bulkPush;
 }

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

@@ -22,12 +22,12 @@ export declare const MIN_HOIST_CORE_VERSION = "28.0";
  */
 export declare class XHApi {
     /** Unique id for this loaded instance of the app.  Unique for every refresh of document. */
-    clientId: string;
+    loadId: string;
     /**
      * Unique id for this browser tab/window on this domain.
      * Corresponds to the scope of the built-in sessionStorage object.
      */
-    sessionId: string;
+    tabId: string;
     /** Core implementation model hosting all application state. */
     appContainerModel: AppContainerModel;
     /** Provider of centralized exception handling for the app. */
@@ -412,8 +412,8 @@ export declare class XHApi {
      */
     genId(): string;
     private get acm();
-    private genClientId;
-    private genSessionId;
+    private genLoadId;
+    private genTabId;
 }
 /** The app-wide singleton instance. */
 export declare const XH: XHApi;

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

@@ -1,5 +1,5 @@
 import { RuleLike } from '@xh/hoist/data';
-import { ReactElement, ReactNode } from 'react';
+import { MouseEvent, ReactElement, ReactNode } from 'react';
 import { LoadSpec } from '../load';
 import { Intent, PlainObject, Thunkable } from './Types';
 /**
@@ -226,7 +226,7 @@ export interface MenuItem {
     /** Css class name to be added when rendering the menu item. */
     className?: string;
     /** Executed when the user clicks the menu item. */
-    actionFn?: () => void;
+    actionFn?: (e: MouseEvent | PointerEvent) => void;
     /** Executed before the item is shown.  Use to adjust properties dynamically. */
     prepareFn?: (me: MenuItem) => void;
     /** Child menu items. */

package/build/types/security/Types.d.ts

@@ -12,28 +12,3 @@ export interface AccessTokenSpec {
     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: number;
-    lastTime: number;
-    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: number;
-        duration: number;
-        code: string;
-        name: string;
-    };
-}

package/build/types/security/msal/MsalClient.d.ts

@@ -3,7 +3,7 @@ import { LogLevel } from '@azure/msal-browser';
 import { PlainObject } from '@xh/hoist/core';
 import { Token } from '@xh/hoist/security/Token';
 import { BaseOAuthClient, BaseOAuthClientConfig } from '../BaseOAuthClient';
-import { AccessTokenSpec, TelemetryResults, TokenMap } from '../Types';
+import { AccessTokenSpec, TokenMap } from '../Types';
 export interface MsalClientConfig extends BaseOAuthClientConfig<MsalTokenSpec> {
     /**
      * Authority for your organization's tenant: `https://login.microsoftonline.com/[tenantId]`.
@@ -19,8 +19,7 @@ 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
+     * Captured performance events will be summarized as {@link MsalClientTelemetry}.
      */
     enableTelemetry?: boolean;
     /**
@@ -88,7 +87,7 @@ export declare class MsalClient extends BaseOAuthClient<MsalClientConfig, MsalTo
     private account;
     private initialTokenLoad;
     /** Enable telemetry via `enableTelemetry` ctor config, or via {@link enableTelemetry}. */
-    telemetryResults: TelemetryResults;
+    telemetry: MsalClientTelemetry;
     private _telemetryCbHandle;
     constructor(config: MsalClientConfig);
     protected doInitAsync(): Promise<TokenMap>;
@@ -108,3 +107,40 @@ export declare class MsalClient extends BaseOAuthClient<MsalClientConfig, MsalTo
     private get refreshOffsetArgs();
     private noteUserAuthenticated;
 }
+/**
+ * Telemetry produced by this client (if enabled) + included in {@link ClientHealthService}
+ * reporting. Leverages MSAL's opt-in support for emitting performance events.
+ * See https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/performance.md
+ */
+interface MsalClientTelemetry {
+    /** Stats across all events */
+    summary: {
+        successCount: number;
+        failureCount: number;
+        maxDuration: number;
+        lastFailureTime: number;
+    };
+    /** Stats by event type */
+    events: Record<string, MsalEventTelemetry>;
+}
+/** Aggregated telemetry results for a single type of event. */
+interface MsalEventTelemetry {
+    firstTime: number;
+    lastTime: number;
+    successCount: number;
+    failureCount: number;
+    /** Timing info (in ms) for event instances reported with duration. */
+    duration?: {
+        count: number;
+        total: number;
+        average: number;
+        max: number;
+    };
+    lastFailure?: {
+        time: number;
+        duration: number;
+        code: string;
+        name: string;
+    };
+}
+export {};

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

@@ -1,43 +1,48 @@
 import { HoistService, PageState, PlainObject } from '@xh/hoist/core';
+import { WebSocketTelemetry } from '@xh/hoist/svc/WebSocketService';
 /**
- * Service for gathering data about client health.
+ * Service for gathering data about the current state and health of the client app, for submission
+ * to the server or review on the console during interactive troubleshooting.
  *
- * Hoist sends this data once on application load, and can be configured to send
- * it at regularly scheduled intervals.  Configure via soft-config property
- * 'xhActivityTracking.clientHealthReport'.
+ * Hoist sends this data once on application load and can be configured to send at regular intervals
+ * throughout a user's session via the `xhActivityTracking.clientHealthReport` app config. Reports
+ * are submitted via activity tracking for review within the Admin Console.
  */
 export declare class ClientHealthService extends HoistService {
     static instance: ClientHealthService;
     private sources;
     initAsync(): Promise<void>;
-    /**
-     * Main entry point.  Return a default report of client health.
-     */
+    get enabled(): boolean;
+    /** @returns a customizable report with metrics capturing client app/session state. */
     getReport(): ClientHealthReport;
-    /** Get report, suitable for viewing in console. **/
+    /** @returns a report, formatted for easier viewing in console. **/
     getFormattedReport(): PlainObject;
     /**
-     * Register a new source for client health report data. No-op if background health report is
-     * not generally enabled via `xhActivityTrackingConfig.clientHealthReport.intervalMins`.
-     *
+     * Register a new source for app-specific data to be sent with each report.
      * @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.
      */
     addSource(key: string, callback: () => any): void;
     /** Unregister a previously-enabled source for client health report data. */
     removeSource(key: string): void;
+    /**
+     * Generate and submit a report to the server, via TrackService.
+     *
+     * For ad-hoc troubleshooting. Apps may also configure this service to
+     * submit on regular intervals.
+     */
+    sendReportAsync(): Promise<void>;
     getGeneral(): GeneralData;
     getConnection(): ConnectionData;
     getMemory(): MemoryData;
     getCustom(): PlainObject;
-    private sendReport;
+    private sendReportInternal;
 }
 export interface GeneralData {
     startTime: number;
     durationMins: number;
     idleMins: number;
     pageState: PageState;
-    webSocket: string;
 }
 export interface ConnectionData {
     downlink: number;
@@ -55,4 +60,5 @@ export interface ClientHealthReport {
     general: GeneralData;
     connection: ConnectionData;
     memory: MemoryData;
+    webSockets: WebSocketTelemetry;
 }

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

@@ -13,7 +13,11 @@ export declare class TrackService extends HoistService {
     get enabled(): boolean;
     /** Track User Activity. */
     track(options: TrackOptions | string): void;
-    private pushPendingAsync;
+    /**
+     * Flush the queue of pending activity tracking messages to the server.
+     * @internal - apps should generally allow this service to manage w/its internal debounce.
+     */
+    pushPendingAsync(): Promise<void>;
     private pushPendingBuffered;
     private toServerJson;
     private logMessage;