@xh/hoist 73.0.0-SNAPSHOT.1744206740883 → 73.0.0-SNAPSHOT.1744229935910

package/CHANGELOG.md

@@ -2,13 +2,17 @@
 
 ## v73.0.0-SNAPSHOT - unreleased
 
-### 🎁 New Features
+## v72.4.0 - 2025-04-09
 
-`ViewManagerConfig` takes new optional key `viewMenuItemFn` to allow ViewManager implementations to customize
-the menu items for views in the view manager menu.
+### 🎁 New Features
+* New methods for formatting timestamps within nested 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.
 
 ### ⚙️ Technical
-* Added enhanced `ClientHealthService` for managing client health report.
+* Added dedicated `ClientHealthService` for managing client health report. Additional enhancements
+  to health report to include information about web sockets, idle time, and page state.
 
 ## v72.3.0 - 2025-04-08
 

package/admin/AdminUtils.ts

@@ -5,9 +5,7 @@
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
 import {XH} from '@xh/hoist/core';
-import {DAYS, LocalDate} from '@xh/hoist/utils/datetime';
-import {isNumber} from 'lodash';
-import {fmtDateTimeSec} from '@xh/hoist/format';
+import {LocalDate} from '@xh/hoist/utils/datetime';
 
 /**
  * Generate a standardized filename for an Admin module grid export, without datestamp.
@@ -23,18 +21,3 @@ export function exportFilename(moduleName: string): string {
 export function exportFilenameWithDate(moduleName: string): () => string {
     return () => `${XH.appCode}-${moduleName}-${LocalDate.today()}`;
 }
-
-/**
- * Replacer for JSON.stringify to replace timestamp properties with formatted strings.
- */
-export function timestampReplacer(k: string, v: any) {
-    if (
-        (k.endsWith('Time') || k.endsWith('Date') || k.endsWith('Timestamp') || k == 'timestamp') &&
-        isNumber(v) &&
-        v > Date.now() - 25 * 365 * DAYS // heuristic to avoid catching smaller ms ranges
-    ) {
-        return fmtDateTimeSec(v, {fmt: 'MMM DD HH:mm:ss.SSS'});
-    }
-
-    return v;
-}

package/admin/tabs/activity/tracking/detail/ActivityDetailModel.ts

@@ -4,14 +4,14 @@
  *
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
-import {exportFilename, timestampReplacer} from '@xh/hoist/admin/AdminUtils';
+import {exportFilename} from '@xh/hoist/admin/AdminUtils';
 import * as Col from '@xh/hoist/admin/columns';
 import {FormModel} from '@xh/hoist/cmp/form';
 import {GridModel} from '@xh/hoist/cmp/grid';
 import {HoistModel, lookup, managed} from '@xh/hoist/core';
 import {action, computed, makeObservable, observable} from '@xh/hoist/mobx';
 import {ActivityTrackingModel} from '../ActivityTrackingModel';
-import {fmtJson} from '@xh/hoist/format';
+import {fmtJson, timestampReplacer} from '@xh/hoist/format';
 
 export class ActivityDetailModel extends HoistModel {
     @lookup(ActivityTrackingModel) activityTrackingModel: ActivityTrackingModel;
@@ -118,7 +118,7 @@ export class ActivityDetailModel extends HoistModel {
         let formattedTrackData = trackData;
         if (formattedTrackData) {
             try {
-                formattedTrackData = fmtJson(trackData, {replacer: timestampReplacer});
+                formattedTrackData = fmtJson(trackData, {replacer: timestampReplacer()});
             } catch (ignored) {}
         }
 

package/admin/tabs/cluster/instances/services/DetailsPanel.ts

@@ -12,8 +12,7 @@ import {panel} from '@xh/hoist/desktop/cmp/panel';
 import {jsonInput} from '@xh/hoist/desktop/cmp/input';
 import {Icon} from '@xh/hoist/icon';
 import {isEmpty} from 'lodash';
-import {fmtJson} from '@xh/hoist/format';
-import {timestampReplacer} from '@xh/hoist/admin/AdminUtils';
+import {fmtJson, timestampReplacer} from '@xh/hoist/format';
 
 export const detailsPanel = hoistCmp.factory({
     model: creates(DetailsModel),
@@ -59,7 +58,7 @@ const stats = hoistCmp.factory<DetailsModel>({
                       enableSearch: true,
                       showFullscreenButton: false,
                       editorProps: {lineNumbers: false},
-                      value: fmtJson(stats, {replacer: timestampReplacer})
+                      value: fmtJson(stats, {replacer: timestampReplacer()})
                   })
               );
     }

package/admin/tabs/cluster/objects/DetailModel.ts

@@ -10,7 +10,7 @@ import {HoistModel, lookup, managed, XH} from '@xh/hoist/core';
 import {StoreRecord} from '@xh/hoist/data';
 import {action, makeObservable, observable} from '@xh/hoist/mobx';
 import {isEmpty, isEqual, without} from 'lodash';
-import {timestampReplacer} from '@xh/hoist/admin/AdminUtils';
+import {withFormattedTimestamps} from '@xh/hoist/format';
 
 export class DetailModel extends HoistModel {
     @lookup(ClusterObjectsModel)
@@ -79,8 +79,7 @@ export class DetailModel extends HoistModel {
         const gridModel = this.createGridModel(diffFields, otherFields);
         gridModel.loadData(
             instanceNames.map(instanceName => {
-                let data = adminStatsByInstance[instanceName] ?? {};
-                data = JSON.parse(JSON.stringify(data, timestampReplacer));
+                const data = withFormattedTimestamps(adminStatsByInstance[instanceName] ?? {});
                 return {instanceName, ...data};
             })
         );

package/admin/tabs/cluster/objects/DetailPanel.ts

@@ -12,8 +12,7 @@ import {panel} from '@xh/hoist/desktop/cmp/panel';
 import {Icon} from '@xh/hoist/icon';
 import {DetailModel} from './DetailModel';
 import './ClusterObjects.scss';
-import {timestampReplacer} from '@xh/hoist/admin/AdminUtils';
-import {fmtJson} from '@xh/hoist/format';
+import {fmtJson, timestampReplacer} from '@xh/hoist/format';
 
 export const detailPanel = hoistCmp.factory({
     model: creates(DetailModel),
@@ -44,7 +43,7 @@ export const detailPanel = hoistCmp.factory({
                         height: '100%',
                         showFullscreenButton: false,
                         editorProps: {lineNumbers: false},
-                        value: fmtJson(selectedAdminStats, {replacer: timestampReplacer})
+                        value: fmtJson(selectedAdminStats, {replacer: timestampReplacer()})
                     })
                 })
             ]

package/appcontainer/AppStateModel.ts

@@ -4,10 +4,10 @@
  *
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
-import {AppState, AppSuspendData, HoistModel, XH} from '@xh/hoist/core';
+import {AppState, AppSuspendData, HoistModel, PlainObject, XH} from '@xh/hoist/core';
 import {action, makeObservable, observable} from '@xh/hoist/mobx';
 import {Timer} from '@xh/hoist/utils/async';
-import {camelCase, isBoolean, isString, mapKeys} from 'lodash';
+import {camelCase, isBoolean, isString, mapKeys, pick} from 'lodash';
 
 /**
  * Support for Core Hoist Application state and loading.
@@ -92,13 +92,14 @@ export class AppStateModel extends HoistModel {
                     timestamp: loadStarted,
                     elapsed: Date.now() - loadStarted - (timings.LOGIN_REQUIRED ?? 0),
                     data: {
-                        appVersion: XH.appVersion,
-                        appBuild: XH.appBuild,
-                        locationHref: window.location.href,
+                        clientId: XH.clientId,
+                        sessionId: XH.sessionId,
                         timings: mapKeys(timings, (v, k) => camelCase(k)),
-                        clientHealth: XH.clientHealthService.getReport()
+                        clientHealth: XH.clientHealthService.getReport(),
+                        window: this.getWindowData(),
+                        screen: this.getScreenData()
                     },
-                    logData: ['appVersion', 'appBuild'],
+                    logData: ['clientId', 'sessionId'],
                     omit: !XH.appSpec.trackAppLoad
                 })
         });
@@ -114,4 +115,36 @@ export class AppStateModel extends HoistModel {
             });
         });
     }
+
+    private getScreenData(): PlainObject {
+        const screen = window.screen as any;
+        if (!screen) return null;
+
+        const ret: PlainObject = pick(screen, [
+            'availWidth',
+            'availHeight',
+            'width',
+            'height',
+            'colorDepth',
+            'pixelDepth',
+            'availLeft',
+            'availTop'
+        ]);
+        if (screen.orientation) {
+            ret.orientation = pick(screen.orientation, ['angle', 'type']);
+        }
+        return ret;
+    }
+
+    private getWindowData(): PlainObject {
+        return pick(window, [
+            'devicePixelRatio',
+            'screenX',
+            'screenY',
+            'innerWidth',
+            'innerHeight',
+            'outerWidth',
+            'outerHeight'
+        ]);
+    }
 }

package/build/types/admin/AdminUtils.d.ts

@@ -7,7 +7,3 @@ export declare function exportFilename(moduleName: string): string;
  * Returned as a closure to ensure current date is evaluated at export time.
  */
 export declare function exportFilenameWithDate(moduleName: string): () => string;
-/**
- * Replacer for JSON.stringify to replace timestamp properties with formatted strings.
- */
-export declare function timestampReplacer(k: string, v: any): any;

package/build/types/appcontainer/AppStateModel.d.ts

@@ -23,4 +23,6 @@ export declare class AppStateModel extends HoistModel {
     checkAccess(): boolean;
     private trackLoad;
     private createActivityListeners;
+    private getScreenData;
+    private getWindowData;
 }

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

@@ -21,6 +21,13 @@ export declare const MIN_HOIST_CORE_VERSION = "28.0";
  * Available via import as `XH` - also installed as `window.XH` for troubleshooting purposes.
  */
 export declare class XHApi {
+    /** Unique id for this loaded instance of the app.  Unique for every refresh of document. */
+    clientId: string;
+    /**
+     * Unique id for this browser tab/window on this domain.
+     * Corresponds to the scope of the built-in sessionStorage object.
+     */
+    sessionId: string;
     /** Core implementation model hosting all application state. */
     appContainerModel: AppContainerModel;
     /** Provider of centralized exception handling for the app. */
@@ -405,6 +412,8 @@ export declare class XHApi {
      */
     genId(): string;
     private get acm();
+    private genClientId;
+    private genSessionId;
 }
 /** The app-wide singleton instance. */
 export declare const XH: XHApi;

package/build/types/format/FormatDate.d.ts

@@ -1,5 +1,5 @@
 import { ReactNode } from 'react';
-import { DateLike } from '../core/types/Types';
+import { DateLike, PlainObject } from '../core/types/Types';
 import { FormatOptions } from './FormatMisc';
 export declare const DATE_FMT = "YYYY-MM-DD", DATETIME_FMT = "YYYY-MM-DD h:mma", DATETIMESEC_FMT = "YYYY-MM-DD h:mm:ssa", TIME_FMT = "h:mma", MONTH_DAY_FMT = "MMM D";
 /**
@@ -49,4 +49,25 @@ export interface CompactDateFormatOptions extends FormatOptions<DateLike> {
  * Render dates formatted based on distance in time from current day.
  */
 export declare function fmtCompactDate(v: DateLike, opts?: CompactDateFormatOptions): ReactNode;
+export interface TimestampReplacerConfig {
+    /**
+     * Suffixes used to identify keys that may hold timestamps.
+     * Defaults to ['time', 'date', 'timestamp']
+     */
+    suffixes?: string[];
+    /**
+     * Format for replaced timestamp.
+     * Defaults to 'MMM DD HH:mm:ss.SSS'
+     */
+    format?: string;
+}
+/**
+ * Replace timestamps in an Object with formatted strings.
+ */
+export declare function withFormattedTimestamps(obj: PlainObject, config?: TimestampReplacerConfig): PlainObject;
+/**
+ * Create a replacer, suitable for JSON.stringify, that will replace timestamps with
+ * formatted strings.
+ */
+export declare function timestampReplacer(config?: TimestampReplacerConfig): (k: string, v: any) => any;
 export declare const dateRenderer: (obj?: string | DateFormatOptions) => (v: DateLike) => ReactNode, dateTimeRenderer: (obj?: string | DateFormatOptions) => (v: any) => ReactNode, dateTimeSecRenderer: (obj?: string | DateFormatOptions) => (v: DateLike) => ReactNode, timeRenderer: (obj?: string | DateFormatOptions) => (v: DateLike) => ReactNode, compactDateRenderer: (obj?: CompactDateFormatOptions) => (v: DateLike) => ReactNode;

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

@@ -19,8 +19,8 @@ export interface TelemetryResults {
 }
 /** Aggregated telemetry results for a single type of event. */
 export interface TelemetryEventResults {
-    firstTime: Date;
-    lastTime: Date;
+    firstTime: number;
+    lastTime: number;
     successCount: number;
     failureCount: number;
     /** Timing info (in ms) for event instances reported with duration. */
@@ -31,7 +31,7 @@ export interface TelemetryEventResults {
         worst: number;
     };
     lastFailure?: {
-        time: Date;
+        time: number;
         duration: number;
         code: string;
         name: string;

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

@@ -1,5 +1,6 @@
 import * as msal from '@azure/msal-browser';
 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';
@@ -96,6 +97,7 @@ export declare class MsalClient extends BaseOAuthClient<MsalClientConfig, MsalTo
     protected fetchIdTokenAsync(useCache?: boolean): Promise<Token>;
     protected fetchAccessTokenAsync(spec: MsalTokenSpec, useCache?: boolean): Promise<Token>;
     protected doLogoutAsync(): Promise<void>;
+    getFormattedTelemetry(): PlainObject;
     enableTelemetry(): void;
     disableTelemetry(): void;
     private loginSsoAsync;

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

@@ -1,4 +1,4 @@
-import { HoistService, PlainObject } from '@xh/hoist/core';
+import { HoistService, PageState, PlainObject } from '@xh/hoist/core';
 /**
  * Service for gathering data about client health.
  *
@@ -11,9 +11,11 @@ export declare class ClientHealthService extends HoistService {
     private sources;
     initAsync(): Promise<void>;
     /**
-     * Main Entry report.  Return a default report of client health.
+     * Main entry point.  Return a default report of client health.
      */
     getReport(): ClientHealthReport;
+    /** Get report, suitable for 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`.
@@ -24,17 +26,18 @@ export declare class ClientHealthService extends HoistService {
     addSource(key: string, callback: () => any): void;
     /** Unregister a previously-enabled source for client health report data. */
     removeSource(key: string): void;
-    getSession(): SessionData;
+    getGeneral(): GeneralData;
     getConnection(): ConnectionData;
     getMemory(): MemoryData;
-    getScreen(): ScreenData;
-    getWindow(): WindowData;
     getCustom(): PlainObject;
     private sendReport;
 }
-export interface SessionData {
+export interface GeneralData {
     startTime: number;
     durationMins: number;
+    idleMins: number;
+    pageState: PageState;
+    webSocket: string;
 }
 export interface ConnectionData {
     downlink: number;
@@ -48,33 +51,8 @@ export interface MemoryData {
     totalJSHeapSize?: number;
     usedJSHeapSize?: number;
 }
-export interface WindowData {
-    devicePixelRatio: number;
-    screenX: number;
-    screenY: number;
-    innerWidth: number;
-    innerHeight: number;
-    outerWidth: number;
-    outerHeight: number;
-}
-export interface ScreenData {
-    availWidth: number;
-    availHeight: number;
-    width: number;
-    height: number;
-    colorDepth: number;
-    pixelDepth: number;
-    availLeft: number;
-    availTop: number;
-    orientation?: {
-        angle: number;
-        type: string;
-    };
-}
 export interface ClientHealthReport {
-    session: SessionData;
+    general: GeneralData;
     connection: ConnectionData;
     memory: MemoryData;
-    window: WindowData;
-    screen: ScreenData;
 }

package/core/XH.ts

@@ -65,6 +65,7 @@ import {
 import {installServicesAsync} from './impl/InstallServices';
 import {instanceManager} from './impl/InstanceManager';
 import {HoistModel, ModelSelector, RefreshContextModel} from './model';
+import ShortUniqueId from 'short-unique-id';
 
 export const MIN_HOIST_CORE_VERSION = '28.0';
 
@@ -85,6 +86,15 @@ declare const xhIsDevelopmentMode: boolean;
  * Available via import as `XH` - also installed as `window.XH` for troubleshooting purposes.
  */
 export class XHApi {
+    /** Unique id for this loaded instance of the app.  Unique for every refresh of document. */
+    clientId: string = this.genClientId();
+
+    /**
+     * Unique id for this browser tab/window on this domain.
+     * Corresponds to the scope of the built-in sessionStorage object.
+     */
+    sessionId: string = this.genSessionId();
+
     //--------------------------
     // Implementation Delegates
     //--------------------------
@@ -796,6 +806,19 @@ export class XHApi {
     private get acm(): AppContainerModel {
         return this.appContainerModel;
     }
+
+    private genClientId(): string {
+        return new ShortUniqueId({length: 8}).rnd();
+    }
+
+    private genSessionId(): string {
+        let ret = window.sessionStorage?.getItem('xhSessionId');
+        if (!ret) {
+            ret = new ShortUniqueId({length: 8}).rnd();
+            window.sessionStorage?.setItem('xhSessionId', ret);
+        }
+        return ret;
+    }
 }
 
 /** The app-wide singleton instance. */

package/format/FormatDate.ts

@@ -4,11 +4,11 @@
  *
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
-import {isLocalDate, LocalDate} from '@xh/hoist/utils/datetime';
-import {defaults, isString} from 'lodash';
+import {DAYS, isLocalDate, LocalDate} from '@xh/hoist/utils/datetime';
+import {defaults, isFinite, isString} from 'lodash';
 import moment from 'moment';
 import {ReactNode} from 'react';
-import {DateLike} from '../core/types/Types';
+import {DateLike, PlainObject} from '../core/types/Types';
 import {fmtSpan, FormatOptions} from './FormatMisc';
 import {createRenderer} from './FormatUtils';
 import {saveOriginal} from './impl/Utils';
@@ -148,6 +148,48 @@ export function fmtCompactDate(v: DateLike, opts?: CompactDateFormatOptions) {
     return fmtDate(v, dateOpts);
 }
 
+export interface TimestampReplacerConfig {
+    /**
+     * Suffixes used to identify keys that may hold timestamps.
+     * Defaults to ['time', 'date', 'timestamp']
+     */
+    suffixes?: string[];
+
+    /**
+     * Format for replaced timestamp.
+     * Defaults to 'MMM DD HH:mm:ss.SSS'
+     */
+    format?: string;
+}
+
+/**
+ * Replace timestamps in an Object with formatted strings.
+ */
+export function withFormattedTimestamps(
+    obj: PlainObject,
+    config: TimestampReplacerConfig = {}
+): PlainObject {
+    return JSON.parse(JSON.stringify(obj, timestampReplacer(config)));
+}
+
+/**
+ * Create a replacer, suitable for JSON.stringify, that will replace timestamps with
+ * formatted strings.
+ */
+export function timestampReplacer(
+    config: TimestampReplacerConfig = {}
+): (k: string, v: any) => any {
+    const suffixes = config.suffixes ?? ['time', 'date', 'timestamp'],
+        fmt = 'MMM DD HH:mm:ss.SSS';
+    return (k: string, v: any) => {
+        return suffixes.some(s => k.toLowerCase().endsWith(s.toLowerCase())) &&
+            isFinite(v) &&
+            v > Date.now() - 25 * 365 * DAYS // heuristic to avoid catching smaller ms ranges
+            ? fmtDateTime(v, {fmt})
+            : v;
+    };
+}
+
 export const dateRenderer = createRenderer(fmtDate),
     dateTimeRenderer = createRenderer(fmtDateTime),
     dateTimeSecRenderer = createRenderer(fmtDateTimeSec),

package/package.json

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

package/security/Types.ts

@@ -31,8 +31,8 @@ export interface TelemetryResults {
 
 /** Aggregated telemetry results for a single type of event. */
 export interface TelemetryEventResults {
-    firstTime: Date;
-    lastTime: Date;
+    firstTime: number;
+    lastTime: number;
     successCount: number;
     failureCount: number;
     /** Timing info (in ms) for event instances reported with duration. */
@@ -43,7 +43,7 @@ export interface TelemetryEventResults {
         worst: number;
     };
     lastFailure?: {
-        time: Date;
+        time: number;
         duration: number;
         code: string;
         name: string;

package/security/msal/MsalClient.ts

@@ -14,9 +14,10 @@ import {
     PopupRequest,
     SilentRequest
 } from '@azure/msal-browser';
-import {XH} from '@xh/hoist/core';
+import {AppState, PlainObject, XH} from '@xh/hoist/core';
 import {Token} from '@xh/hoist/security/Token';
 import {logDebug, logError, logInfo, logWarn, mergeDeep, throwIf} from '@xh/hoist/utils/js';
+import {withFormattedTimestamps} from '@xh/hoist/format';
 import {flatMap, union, uniq} from 'lodash';
 import {BaseOAuthClient, BaseOAuthClientConfig} from '../BaseOAuthClient';
 import {AccessTokenSpec, TelemetryResults, TokenMap} from '../Types';
@@ -266,9 +267,13 @@ export class MsalClient extends BaseOAuthClient<MsalClientConfig, MsalTokenSpec>
     //------------------------
     // Telemetry
     //------------------------
+    getFormattedTelemetry(): PlainObject {
+        return withFormattedTimestamps(this.telemetryResults);
+    }
+
     enableTelemetry(): void {
         if (this._telemetryCbHandle) {
-            this.logInfo('Telemetry already enabled', this.telemetryResults);
+            this.logInfo('Telemetry already enabled', this.getFormattedTelemetry());
             return;
         }
 
@@ -279,7 +284,7 @@ export class MsalClient extends BaseOAuthClient<MsalClientConfig, MsalTokenSpec>
                 try {
                     const {events} = this.telemetryResults,
                         {name, startTimeMs, durationMs, success, errorName, errorCode} = e,
-                        eTime = startTimeMs ? new Date(startTimeMs) : new Date();
+                        eTime = startTimeMs ?? Date.now();
 
                     const eResult = (events[name] ??= {
                         firstTime: eTime,
@@ -316,10 +321,9 @@ export class MsalClient extends BaseOAuthClient<MsalClientConfig, MsalTokenSpec>
             });
         });
 
-        // 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.)
+        // Wait for clientHealthService (this client likely initialized during earlier AUTHENTICATING.)
         this.addReaction({
-            when: () => XH.appIsRunning,
+            when: () => XH.appState === AppState.INITIALIZING_APP,
             run: () => XH.clientHealthService.addSource('msalClient', () => this.telemetryResults)
         });
 
@@ -336,7 +340,7 @@ export class MsalClient extends BaseOAuthClient<MsalClientConfig, MsalTokenSpec>
         this._telemetryCbHandle = null;
 
         XH.clientHealthService.removeSource('msalClient');
-        this.logInfo('Telemetry disabled', this.telemetryResults);
+        this.logInfo('Telemetry disabled', this.getFormattedTelemetry());
     }
 
     //------------------------