@xh/hoist 73.0.0-SNAPSHOT.1744228975863 → 73.0.0-SNAPSHOT.1744281639439

package/CHANGELOG.md

@@ -2,18 +2,18 @@
 
 ## v73.0.0-SNAPSHOT - unreleased
 
+## v72.4.0 - 2025-04-09
+
 ### 🎁 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.
+* `ViewManagerConfig` takes new optional key `viewMenuItemFn` to allow ViewManager implementations
+  to customize the menu items for views in the view manager menu.
 
 ### ⚙️ Technical
-* Added dedicated `ClientHealthService` for managing client health report.  Additional enhancements
+* 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
 
 ### 🎁 New Features

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

@@ -1,36 +1,41 @@
 import { HoistService, PageState, PlainObject } from '@xh/hoist/core';
 /**
- * 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;

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;

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/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/package.json

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

package/svc/ClientHealthService.ts

@@ -4,18 +4,19 @@
  *
  * 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 {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,15 +26,17 @@ 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(),
@@ -43,15 +46,13 @@ export class ClientHealthService extends HoistService {
         };
     }
 
-    /** 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 +65,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
     //------------------------------------
@@ -117,16 +129,17 @@ 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,

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();