@xh/hoist 72.4.0 → 72.5.0

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

@@ -1,4 +1,4 @@
-import { HoistService } from '@xh/hoist/core';
+import { HoistService, PlainObject } from '@xh/hoist/core';
 /**
  * Establishes and maintains a websocket connection to the Hoist server, if enabled via `AppSpec`.
  *
@@ -27,6 +27,10 @@ export declare class WebSocketService extends HoistService {
     readonly HEARTBEAT_TOPIC = "xhHeartbeat";
     readonly REG_SUCCESS_TOPIC = "xhRegistrationSuccess";
     readonly FORCE_APP_SUSPEND_TOPIC = "xhForceAppSuspend";
+    readonly REQ_CLIENT_HEALTH_RPT_TOPIC = "xhRequestClientHealthReport";
+    readonly METADATA_FOR_HANDSHAKE: string[];
+    /** True if WebSockets generally enabled - set statically in code via {@link AppSpec}. */
+    enabled: boolean;
     /** Unique channel assigned by server upon successful connection. */
     channelKey: string;
     /** Last time a message was received, including heartbeat messages. */
@@ -35,10 +39,10 @@ export declare class WebSocketService extends HoistService {
     get connected(): boolean;
     /** Set to true to log all sent/received messages - very chatty. */
     logMessages: boolean;
+    telemetry: WebSocketTelemetry;
     private _timer;
     private _socket;
     private _subsByTopic;
-    enabled: boolean;
     constructor();
     initAsync(): Promise<void>;
     /**
@@ -61,23 +65,24 @@ export declare class WebSocketService extends HoistService {
      * Send a message back to the server via the connected websocket.
      */
     sendMessage(message: WebSocketMessage): void;
-    connect(): void;
-    disconnect(): void;
-    heartbeatOrReconnect(): void;
-    private onServerInstanceChange;
     shutdown(): void;
+    getFormattedTelemetry(): PlainObject;
+    private connect;
+    private disconnect;
+    private heartbeatOrReconnect;
+    private onServerInstanceChange;
     onOpen(ev: any): void;
     onClose(ev: any): void;
     onError(ev: any): void;
-    onMessage(rawMsg: any): void;
-    notifySubscribers(message: any): void;
-    getSubsForTopic(topic: any): WebSocketSubscription[];
-    updateConnectedStatus(): void;
-    installChannelKey(key: any): void;
-    updateLastMessageTime(): void;
-    buildWebSocketUrl(): string;
-    showTestMessageAlert(message: any): void;
-    maybeLogMessage(...args: any[]): void;
+    onMessage(rawMsg: MessageEvent): void;
+    private notifySubscribers;
+    private getSubsForTopic;
+    private updateConnectedStatus;
+    private installChannelKey;
+    private updateLastMessageTime;
+    private buildWebSocketUrl;
+    private maybeLogMessage;
+    private noteTelemetryEvent;
 }
 /**
  * Wrapper class to encapsulate and manage a subscription to messages for a given topic + handler.
@@ -93,3 +98,21 @@ export interface WebSocketMessage {
     topic: string;
     data?: any;
 }
+/** Telemetry collected by this service + included in {@link ClientHealthService} reporting. */
+export interface WebSocketTelemetry {
+    channelKey: string;
+    subscriptionCount: number;
+    events: {
+        connOpened?: WebSocketEventTelemetry;
+        connClosed?: WebSocketEventTelemetry;
+        connError?: WebSocketEventTelemetry;
+        msgReceived?: WebSocketEventTelemetry;
+        msgSent?: WebSocketEventTelemetry;
+        heartbeatReconnectAttempt?: WebSocketEventTelemetry;
+        instanceChangeReconnectAttempt?: WebSocketEventTelemetry;
+    };
+}
+export interface WebSocketEventTelemetry {
+    count: number;
+    lastTime: number;
+}

package/core/XH.ts

@@ -87,13 +87,13 @@ declare const xhIsDevelopmentMode: boolean;
  */
 export class XHApi {
     /** Unique id for this loaded instance of the app.  Unique for every refresh of document. */
-    clientId: string = this.genClientId();
+    loadId: string = this.genLoadId();
 
     /**
      * Unique id for this browser tab/window on this domain.
      * Corresponds to the scope of the built-in sessionStorage object.
      */
-    sessionId: string = this.genSessionId();
+    tabId: string = this.genTabId();
 
     //--------------------------
     // Implementation Delegates
@@ -807,15 +807,15 @@ export class XHApi {
         return this.appContainerModel;
     }
 
-    private genClientId(): string {
+    private genLoadId(): string {
         return new ShortUniqueId({length: 8}).rnd();
     }
 
-    private genSessionId(): string {
-        let ret = window.sessionStorage?.getItem('xhSessionId');
+    private genTabId(): string {
+        let ret = window.sessionStorage?.getItem('xhTabId');
         if (!ret) {
             ret = new ShortUniqueId({length: 8}).rnd();
-            window.sessionStorage?.setItem('xhSessionId', ret);
+            window.sessionStorage?.setItem('xhTabId', ret);
         }
         return ret;
     }

package/core/types/Interfaces.ts

@@ -6,7 +6,7 @@
  */
 
 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';
 
@@ -284,7 +284,7 @@ export interface MenuItem {
     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;

package/data/filter/BaseFilterFieldSpec.ts

@@ -6,7 +6,7 @@
  */
 import {HoistBase} from '@xh/hoist/core';
 import {Field, Store, FieldFilter, FieldType, genDisplayName, View} from '@xh/hoist/data';
-import {isEmpty} from 'lodash';
+import {compact, isArray, isEmpty} from 'lodash';
 import {FieldFilterOperator} from './Types';
 
 export interface BaseFilterFieldSpecConfig {
@@ -72,7 +72,11 @@ export abstract class BaseFilterFieldSpec extends HoistBase {
         this.displayName = displayName ?? sourceField?.displayName ?? genDisplayName(field);
         this.ops = this.parseOperators(ops);
         this.forceSelection = forceSelection ?? false;
-        this.values = values ?? (this.isBoolFieldType ? [true, false] : null);
+        this.values = isArray(values)
+            ? compact(values)
+            : this.isBoolFieldType
+              ? [true, false]
+              : null;
         this.hasExplicitValues = !isEmpty(this.values);
         this.enableValues = this.hasExplicitValues || (enableValues ?? this.isEnumerableByDefault);
     }

package/desktop/appcontainer/AboutDialog.ts

@@ -42,10 +42,24 @@ export const aboutDialog = hoistCmp.factory({
                     item: model.getTable()
                 }),
                 toolbar(
+                    button({
+                        text: 'Send Client Health Report',
+                        icon: Icon.health(),
+                        omit: !XH.clientHealthService.enabled,
+                        onClick: async () => {
+                            try {
+                                await XH.clientHealthService.sendReportAsync();
+                                XH.successToast('Client health report successfully submitted.');
+                            } catch (e) {
+                                XH.handleException('Error sending client health report', e);
+                            }
+                        }
+                    }),
                     filler(),
                     button({
                         text: 'Close',
                         intent: 'primary',
+                        outlined: true,
                         onClick: onClose
                     })
                 )

package/desktop/cmp/button/AppMenuButton.ts

@@ -202,7 +202,7 @@ function parseMenuItems(items: MenuItemLike[]): ReactNode[] {
                 icon: item.icon,
                 intent: item.intent,
                 className: item.className,
-                onClick: actionFn ? () => wait().then(actionFn) : null, // do async to allow menu to close
+                onClick: actionFn ? e => wait().then(() => actionFn(e)) : null, // do async to allow menu to close
                 disabled: item.disabled
             };
 

package/desktop/cmp/contextmenu/ContextMenu.ts

@@ -70,7 +70,7 @@ function parseItems(items: MenuItemLike[]): ReactNode[] {
                 icon: item.icon,
                 intent: item.intent,
                 className: item.className,
-                onClick: item.actionFn ? () => wait().then(item.actionFn) : null, // do async to allow menu to close
+                onClick: item.actionFn ? e => wait().then(() => item.actionFn(e)) : null, // do async to allow menu to close
                 popoverProps: {usePortal: true},
                 disabled: item.disabled,
                 items

package/kit/onsen/theme.scss

@@ -118,6 +118,11 @@ body.xh-app.xh-mobile {
     color: var(--xh-text-color);
   }
 
+  // Toast - ensure z-index exceeds dialogs
+  ons-toast {
+    z-index: 30001 !important;
+  }
+
   // Remove outlines
   .tabbar__button:focus {
     outline: none;

package/mobile/appcontainer/AboutDialog.scss

@@ -6,7 +6,7 @@
 
   th {
     text-align: right;
-    vertical-align: top;
+    vertical-align: middle;
     white-space: nowrap;
     background-color: var(--xh-bg-alt);
     border-bottom: var(--xh-border-solid);

package/mobile/appcontainer/AboutDialog.ts

@@ -30,7 +30,30 @@ export const aboutDialog = hoistCmp.factory({
             className: 'xh-about-dialog',
             item: model.getTable(),
             isOpen: model.isOpen,
-            bbar: [filler(), button({text: 'Close', onClick: () => model.hide()})]
+            bbar: [
+                button({
+                    text: 'Send Client Health Report',
+                    icon: Icon.health(),
+                    omit: !XH.clientHealthService.enabled,
+                    onClick: async () => {
+                        try {
+                            await XH.clientHealthService.sendReportAsync();
+                            XH.successToast({
+                                message: 'Client health report submitted.',
+                                timeout: 2000
+                            });
+                        } catch (e) {
+                            XH.handleException('Error sending client health report', e);
+                        }
+                    }
+                }),
+                filler(),
+                button({
+                    text: 'Close',
+                    outlined: true,
+                    onClick: () => model.hide()
+                })
+            ]
         });
     }
 });

package/mobile/cmp/menu/impl/Menu.ts

@@ -98,9 +98,9 @@ class LocalMenuModel extends HoistModel {
                     omit: hidden,
                     onTouchStart: () => (this.pressedIdx = idx),
                     onTouchEnd: () => (this.pressedIdx = null),
-                    onClick: () => {
+                    onClick: e => {
                         this.pressedIdx = null;
-                        if (actionFn) actionFn();
+                        if (actionFn) actionFn(e);
                         onDismiss();
                     }
                 });

package/package.json

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

package/security/Types.ts

@@ -22,30 +22,3 @@ export interface AccessTokenSpec {
 }
 
 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/security/msal/MsalClient.ts

@@ -20,7 +20,7 @@ import {logDebug, logError, logInfo, logWarn, mergeDeep, throwIf} from '@xh/hois
 import {withFormattedTimestamps} from '@xh/hoist/format';
 import {flatMap, union, uniq} from 'lodash';
 import {BaseOAuthClient, BaseOAuthClientConfig} from '../BaseOAuthClient';
-import {AccessTokenSpec, TelemetryResults, TokenMap} from '../Types';
+import {AccessTokenSpec, TokenMap} from '../Types';
 
 export interface MsalClientConfig extends BaseOAuthClientConfig<MsalTokenSpec> {
     /**
@@ -39,8 +39,7 @@ export interface MsalClientConfig extends BaseOAuthClientConfig<MsalTokenSpec> {
 
     /**
      * 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;
 
@@ -115,7 +114,7 @@ export class MsalClient extends BaseOAuthClient<MsalClientConfig, MsalTokenSpec>
     private initialTokenLoad: boolean;
 
     /** Enable telemetry via `enableTelemetry` ctor config, or via {@link enableTelemetry}. */
-    telemetryResults: TelemetryResults = {events: {}};
+    telemetry: MsalClientTelemetry = null;
     private _telemetryCbHandle: string = null;
 
     constructor(config: MsalClientConfig) {
@@ -268,7 +267,7 @@ export class MsalClient extends BaseOAuthClient<MsalClientConfig, MsalTokenSpec>
     // Telemetry
     //------------------------
     getFormattedTelemetry(): PlainObject {
-        return withFormattedTimestamps(this.telemetryResults);
+        return withFormattedTimestamps(this.telemetry);
     }
 
     enableTelemetry(): void {
@@ -277,12 +276,20 @@ export class MsalClient extends BaseOAuthClient<MsalClientConfig, MsalTokenSpec>
             return;
         }
 
-        this.telemetryResults = {events: {}};
+        this.telemetry = {
+            summary: {
+                successCount: 0,
+                failureCount: 0,
+                maxDuration: 0,
+                lastFailureTime: null
+            },
+            events: {}
+        };
 
         this._telemetryCbHandle = this.client.addPerformanceCallback(events => {
             events.forEach(e => {
                 try {
-                    const {events} = this.telemetryResults,
+                    const {summary, events} = this.telemetry,
                         {name, startTimeMs, durationMs, success, errorName, errorCode} = e,
                         eTime = startTimeMs ?? Date.now();
 
@@ -290,15 +297,16 @@ export class MsalClient extends BaseOAuthClient<MsalClientConfig, MsalTokenSpec>
                         firstTime: eTime,
                         lastTime: eTime,
                         successCount: 0,
-                        failureCount: 0,
-                        duration: {count: 0, total: 0, average: 0, worst: 0},
-                        lastFailure: null
+                        failureCount: 0
                     });
                     eResult.lastTime = eTime;
 
                     if (success) {
+                        summary.successCount++;
                         eResult.successCount++;
                     } else {
+                        summary.failureCount++;
+                        summary.lastFailureTime = eTime;
                         eResult.failureCount++;
                         eResult.lastFailure = {
                             time: eTime,
@@ -309,11 +317,17 @@ export class MsalClient extends BaseOAuthClient<MsalClientConfig, MsalTokenSpec>
                     }
 
                     if (durationMs) {
-                        const {duration} = eResult;
+                        const duration = (eResult.duration ??= {
+                            count: 0,
+                            total: 0,
+                            average: 0,
+                            max: 0
+                        });
                         duration.count++;
                         duration.total += durationMs;
                         duration.average = Math.round(duration.total / duration.count);
-                        duration.worst = Math.max(duration.worst, durationMs);
+                        duration.max = Math.max(duration.max, durationMs);
+                        summary.maxDuration = Math.max(summary.maxDuration, durationMs);
                     }
                 } catch (e) {
                     this.logError(`Error processing telemetry event`, e);
@@ -324,10 +338,10 @@ export class MsalClient extends BaseOAuthClient<MsalClientConfig, MsalTokenSpec>
         // Wait for clientHealthService (this client likely initialized during earlier AUTHENTICATING.)
         this.addReaction({
             when: () => XH.appState === AppState.INITIALIZING_APP,
-            run: () => XH.clientHealthService.addSource('msalClient', () => this.telemetryResults)
+            run: () => XH.clientHealthService.addSource('msalClient', () => this.telemetry)
         });
 
-        this.logInfo('Telemetry enabled');
+        this.logDebug('Telemetry enabled');
     }
 
     disableTelemetry(): void {
@@ -434,3 +448,41 @@ export class MsalClient extends BaseOAuthClient<MsalClientConfig, MsalTokenSpec>
         this.logDebug('User Authenticated', account.username);
     }
 }
+
+/**
+ * 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;
+    };
+}

package/svc/ClientHealthService.ts

@@ -4,18 +4,20 @@
  *
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
-import {HoistService, PageState, PlainObject, XH} from '@xh/hoist/core';
+import {HoistService, PageState, PlainObject, TrackOptions, XH} from '@xh/hoist/core';
+import {WebSocketTelemetry} from '@xh/hoist/svc/WebSocketService';
 import {Timer} from '@xh/hoist/utils/async';
 import {MINUTES} from '@xh/hoist/utils/datetime';
 import {withFormattedTimestamps} from '@xh/hoist/format';
 import {pick, round} from 'lodash';
 
 /**
- * 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 class ClientHealthService extends HoistService {
     static instance: ClientHealthService;
@@ -25,33 +27,34 @@ export class ClientHealthService extends HoistService {
     override async initAsync() {
         const {clientHealthReport} = XH.trackService.conf;
         Timer.create({
-            runFn: () => this.sendReport(),
+            runFn: () => this.sendReportInternal(),
             interval: clientHealthReport.intervalMins * MINUTES,
             delay: true
         });
     }
 
-    /**
-     * Main entry point.  Return a default report of client health.
-     */
+    get enabled(): boolean {
+        return XH.trackService.enabled;
+    }
+
+    /** @returns a customizable report with metrics capturing client app/session state. */
     getReport(): ClientHealthReport {
         return {
             general: this.getGeneral(),
             memory: this.getMemory(),
             connection: this.getConnection(),
+            webSockets: XH.webSocketService.telemetry,
             ...this.getCustom()
         };
     }
 
-    /** Get report, suitable for viewing in console. **/
+    /** @returns a report, formatted for easier viewing in console. **/
     getFormattedReport(): PlainObject {
         return withFormattedTimestamps(this.getReport());
     }
 
     /**
-     * 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.
      */
@@ -64,6 +67,17 @@ export class ClientHealthService extends HoistService {
         this.sources.delete(key);
     }
 
+    /**
+     * 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.
+     */
+    async sendReportAsync() {
+        this.sendReportInternal({severity: 'INFO'});
+        await XH.trackService.pushPendingAsync();
+    }
+
     // -----------------------------------
     // Generate individual report sections
     //------------------------------------
@@ -75,8 +89,7 @@ export class ClientHealthService extends HoistService {
             startTime,
             durationMins: elapsedMins(startTime),
             idleMins: elapsedMins(XH.lastActivityMs),
-            pageState: XH.pageState,
-            webSocket: XH.webSocketService.channelKey
+            pageState: XH.pageState
         };
     }
 
@@ -117,19 +130,20 @@ export class ClientHealthService extends HoistService {
         return ret;
     }
 
-    //------------------
+    //---------------------
     // Implementation
-    //------------------
-    private sendReport() {
+    //---------------------
+    private sendReportInternal(opts: Partial<TrackOptions> = {}) {
         const {intervalMins, ...rest} = XH.trackService.conf.clientHealthReport ?? {};
 
         XH.track({
             category: 'App',
             message: 'Submitted health report',
             ...rest,
+            ...opts,
             data: {
-                clientId: XH.clientId,
-                sessionId: XH.sessionId,
+                loadId: XH.loadId,
+                tabId: XH.tabId,
                 ...this.getReport()
             }
         });
@@ -141,7 +155,6 @@ export interface GeneralData {
     durationMins: number;
     idleMins: number;
     pageState: PageState;
-    webSocket: string;
 }
 
 export interface ConnectionData {
@@ -162,4 +175,5 @@ export interface ClientHealthReport {
     general: GeneralData;
     connection: ConnectionData;
     memory: MemoryData;
+    webSockets: WebSocketTelemetry;
 }

package/svc/TrackService.ts

@@ -90,10 +90,11 @@ export class TrackService extends HoistService {
         this.pushPendingBuffered();
     }
 
-    //------------------
-    // Implementation
-    //------------------
-    private async 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.
+     */
+    async pushPendingAsync() {
         const {pending} = this;
         if (isEmpty(pending)) return;
 
@@ -105,6 +106,9 @@ export class TrackService extends HoistService {
         });
     }
 
+    //------------------
+    // Implementation
+    //------------------
     @debounced(10 * SECONDS)
     private pushPendingBuffered() {
         this.pushPendingAsync();