@xh/hoist 83.1.0 → 84.0.1

package/mobile/appcontainer/ImpersonationBar.ts

@@ -37,11 +37,13 @@ export const impersonationBar = hoistCmp.factory({
                     enableFullscreen: true,
                     placeholder: 'Select a user to impersonate...',
                     createMessageFn: q => `Impersonate new user "${q}"`,
+                    testId: 'xh-impersonation-target',
                     onCommit: model.onCommit
                 }),
                 button({
                     icon: Icon.close(),
                     minimal: true,
+                    testId: 'xh-impersonation-exit-btn',
                     onClick: model.onClose
                 })
             ]

package/mobile/appcontainer/LockoutPanel.ts

@@ -39,6 +39,7 @@ export const lockoutPanel = hoistCmp.factory<AppContainerModel>({
                     button({
                         icon: Icon.logout(),
                         text: 'Logout',
+                        testId: 'xh-lockout-logout-btn',
                         omit: !appSpec.enableLogout,
                         onClick: () => XH.logoutAsync()
                     }),
@@ -46,6 +47,7 @@ export const lockoutPanel = hoistCmp.factory<AppContainerModel>({
                     button({
                         icon: Icon.impersonate(),
                         text: 'End Impersonation',
+                        testId: 'xh-lockout-end-impersonation-btn',
                         omit: !identityService.isImpersonating,
                         onClick: () => identityService.endImpersonateAsync()
                     })

package/mobile/appcontainer/LoginPanel.ts

@@ -30,6 +30,7 @@ export const loginPanel = hoistCmp.factory({
 
         return panel({
             className: 'xh-login',
+            testId: 'xh-login',
             items: [
                 toolbar(filler(), XH.clientAppName, filler()),
                 panel({
@@ -44,14 +45,16 @@ export const loginPanel = hoistCmp.factory({
                                     placeholder: 'Username',
                                     autoComplete: 'username',
                                     autoCapitalize: 'none',
-                                    commitOnChange: true
+                                    commitOnChange: true,
+                                    testId: 'xh-login-username'
                                 }),
                                 textInput({
                                     bind: 'password',
                                     placeholder: 'Password',
                                     autoComplete: 'current-password',
                                     type: 'password',
-                                    commitOnChange: true
+                                    commitOnChange: true,
+                                    testId: 'xh-login-password'
                                 })
                             ]
                         }),
@@ -69,7 +72,8 @@ export const loginPanel = hoistCmp.factory({
                             icon: Icon.login(),
                             text: loginInProgress ? 'Please wait...' : 'Login',
                             disabled: !isValid || loginInProgress,
-                            onClick: () => model.submitAsync()
+                            onClick: () => model.submitAsync(),
+                            testId: 'xh-login-btn'
                         })
                     ]
                 })

package/mobile/appcontainer/Message.ts

@@ -31,7 +31,7 @@ export const message = hoistCmp.factory({
         if (!isOpen) return null;
 
         if (cancelProps) {
-            buttons.push(button({minimal: true, ...cancelProps}));
+            buttons.push(button({testId: 'xh-message-cancel-btn', minimal: true, ...cancelProps}));
         }
 
         if (cancelProps || confirmProps) {
@@ -46,8 +46,12 @@ export const message = hoistCmp.factory({
             // Merge in formModel.isValid here in render stage to get reactivity.
             buttons.push(
                 formModel
-                    ? button({...confirmProps, disabled: !formModel.isValid})
-                    : button(confirmProps)
+                    ? button({
+                          testId: 'xh-message-confirm-btn',
+                          ...confirmProps,
+                          disabled: !formModel.isValid
+                      })
+                    : button({testId: 'xh-message-confirm-btn', ...confirmProps})
             );
         }
 
@@ -76,6 +80,7 @@ const inputCmp = hoistCmp.factory<MessageModel>(({model}) => {
         items.push(
             formField({
                 field: 'value',
+                testId: 'xh-message-value',
                 item: withDefault(input.item, textInput())
             })
         );
@@ -85,6 +90,7 @@ const inputCmp = hoistCmp.factory<MessageModel>(({model}) => {
             formField({
                 label: extraConfirmLabel,
                 field: 'extraConfirm',
+                testId: 'xh-message-extra-confirm',
                 item: textInput()
             })
         );

package/mobile/appcontainer/OptionsDialog.ts

@@ -30,6 +30,7 @@ export const optionsDialog = hoistCmp.factory({
             title: `${XH.clientAppName} Options`,
             icon: Icon.options(),
             className: 'xh-options-dialog',
+            testId: 'xh-options-dialog',
             isOpen: true,
             item: [
                 mask({bind: loadTask, spinner: true}),
@@ -43,7 +44,8 @@ export const optionsDialog = hoistCmp.factory({
                             restoreDefaultsButton({
                                 intent: 'danger',
                                 minimal: false,
-                                className: 'xh-options-dialog__restore-defaults-btn'
+                                className: 'xh-options-dialog__restore-defaults-btn',
+                                testId: 'xh-options-restore-defaults-btn'
                             })
                         ]
                     })
@@ -54,6 +56,7 @@ export const optionsDialog = hoistCmp.factory({
                 button({
                     text: 'Cancel',
                     minimal: true,
+                    testId: 'xh-options-cancel-btn',
                     onClick: () => model.hide()
                 }),
                 button({
@@ -62,6 +65,7 @@ export const optionsDialog = hoistCmp.factory({
                     intent: 'primary',
                     outlined: true,
                     disabled: !formModel.isDirty,
+                    testId: 'xh-options-save-btn',
                     onClick: () => model.saveAsync()
                 })
             ]

package/mobile/appcontainer/VersionBar.ts

@@ -27,6 +27,7 @@ export const versionBar = hoistCmp.factory({
             alignItems: 'center',
             flex: 'none',
             className: `xh-version-bar xh-version-bar--${env.toLowerCase()}`,
+            testId: 'xh-version-bar',
             items: [
                 [env, version, tabId].join(' • '),
                 button({

package/mobile/appcontainer/suspend/IdlePanel.ts

@@ -5,15 +5,12 @@
  * Copyright © 2026 Extremely Heavy Industries Inc.
  */
 
-import {XH, hoistCmp} from '@xh/hoist/core';
-import {vframe, div, img, p} from '@xh/hoist/cmp/layout';
-import {panel} from '@xh/hoist/mobile/cmp/panel';
+import {div, img, p, vframe} from '@xh/hoist/cmp/layout';
+import {hoistCmp, XH} from '@xh/hoist/core';
 import {Icon} from '@xh/hoist/icon';
 import {button} from '@xh/hoist/mobile/cmp/button';
-
 import './IdlePanel.scss';
-
-// @ts-ignore
+import {panel} from '@xh/hoist/mobile/cmp/panel';
 import idleImage from './IdlePanelImage.png';
 
 /**
@@ -28,6 +25,7 @@ export const idlePanel = hoistCmp.factory({
     render({onReactivate}) {
         return panel({
             className: 'xh-idle-panel',
+            testId: 'xh-idle-panel',
             title: `${XH.clientAppName} is sleeping`,
             icon: Icon.moon(),
             items: [
@@ -47,6 +45,7 @@ export const idlePanel = hoistCmp.factory({
                             item: button({
                                 text: "I'm back!",
                                 flex: 1,
+                                testId: 'xh-idle-reactivate-btn',
                                 onClick: onReactivate
                             })
                         })

package/mobile/appcontainer/suspend/SuspendPanel.ts

@@ -53,6 +53,7 @@ export const suspendPanel = hoistCmp.factory<AppContainerModel>({
 
         return panel({
             className: 'xh-suspend-panel',
+            testId: 'xh-suspend-panel',
             title,
             icon,
             items: [
@@ -74,12 +75,14 @@ export const suspendPanel = hoistCmp.factory<AppContainerModel>({
                                     icon: Icon.refresh(),
                                     intent: 'primary',
                                     flex: 1,
+                                    testId: 'xh-suspend-reload-btn',
                                     onClick: () => XH.reloadApp()
                                 }),
                                 button({
                                     text: 'More Details',
                                     icon: Icon.detail(),
                                     minimal: true,
+                                    testId: 'xh-suspend-details-btn',
                                     omit: !exception,
                                     onClick: () =>
                                         XH.exceptionHandler.showExceptionDetails(exception)

package/mobile/cmp/navigator/NavigatorModel.ts

@@ -14,6 +14,14 @@ import '@xh/hoist/mobile/register';
 import {PageConfig, PageModel} from './PageModel';
 import {findScrollableParent, isDraggableEl} from './impl/Utils';
 
+/**
+ * Configuration for a {@link NavigatorModel} - the primary stack-based navigation controller
+ * for mobile Hoist apps. Supports swipe-based page transitions, pull-to-refresh, and
+ * configurable render/refresh strategies.
+ *
+ * @see NavigatorModel
+ * @see PageConfig
+ */
 export interface NavigatorConfig {
     /** Configs for PageModels, representing all supported pages within this Navigator/App. */
     pages: PageConfig[];

package/mobile/cmp/navigator/PageModel.ts

@@ -19,6 +19,13 @@ import {warnIf, withDefault} from '@xh/hoist/utils/js';
 import {stringify} from 'qs';
 import {NavigatorModel} from './NavigatorModel';
 
+/**
+ * Configuration for a {@link PageModel} - a single page within a {@link NavigatorModel}.
+ * Passed as entries in the `pages` array of a {@link NavigatorConfig}.
+ *
+ * @see PageModel
+ * @see NavigatorConfig
+ */
 export interface PageConfig {
     /** Unique ID. Must match a configured Router5 route name. */
     id: string;

package/mobile/cmp/panel/DialogPanel.ts

@@ -20,8 +20,6 @@ export interface DialogPanelProps extends PanelProps {
  *
  * These views do not participate in navigation or routing, and are used for showing fullscreen
  * views outside of the Navigator / TabContainer context.
- *
- * @see FullscreenPanel for a true fullscreen, non-floating alternative.
  */
 export const [DialogPanel, dialogPanel] = hoistCmp.withFactory<DialogPanelProps>({
     displayName: 'DialogPanel',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xh/hoist",
-  "version": "83.1.0",
+  "version": "84.0.1",
   "description": "Hoist add-on for building and deploying React Applications.",
   "repository": {
     "type": "git",
@@ -38,17 +38,17 @@
     ]
   },
   "dependencies": {
-    "@auth0/auth0-spa-js": "~2.17.0",
+    "@auth0/auth0-spa-js": "~2.19.0",
     "@azure/msal-browser": "~4.29.0",
     "@blueprintjs/core": "^6.3.2",
     "@blueprintjs/datetime": "^6.0.6",
-    "@fortawesome/fontawesome-pro": "^6.6.0",
-    "@fortawesome/fontawesome-svg-core": "^6.6.0",
-    "@fortawesome/pro-light-svg-icons": "^6.6.0",
-    "@fortawesome/pro-regular-svg-icons": "^6.6.0",
-    "@fortawesome/pro-solid-svg-icons": "^6.6.0",
-    "@fortawesome/pro-thin-svg-icons": "^6.6.0",
-    "@fortawesome/react-fontawesome": "^0.2.3",
+    "@fortawesome/fontawesome-pro": "^7.2.0",
+    "@fortawesome/fontawesome-svg-core": "^7.2.0",
+    "@fortawesome/pro-light-svg-icons": "^7.2.0",
+    "@fortawesome/pro-regular-svg-icons": "^7.2.0",
+    "@fortawesome/pro-solid-svg-icons": "^7.2.0",
+    "@fortawesome/pro-thin-svg-icons": "^7.2.0",
+    "@fortawesome/react-fontawesome": "^3.2.0",
     "@modelcontextprotocol/sdk": "^1.26.0",
     "@onsenui/fastclick": "~1.1.1",
     "@popperjs/core": "~2.11.0",
@@ -59,7 +59,7 @@
     "commander": "^14.0.3",
     "core-js": "3.x",
     "debounce-promise": "~3.1.0",
-    "dompurify": "~3.3.0",
+    "dompurify": "~3.4.0",
     "fast-deep-equal": "~3.1.1",
     "filesize": "~11.0.2",
     "golden-layout": "~1.5.9",
@@ -67,7 +67,7 @@
     "inter-ui": "~4.1.1",
     "jquery": "3.x",
     "jwt-decode": "~4.0.0",
-    "lodash": "~4.17.21",
+    "lodash": "~4.18.0",
     "lodash-inflection": "~1.5.0",
     "mobx": "~6.15.0",
     "mobx-react-lite": "~4.1.0",

package/security/BaseOAuthClient.ts

@@ -20,6 +20,15 @@ import ShortUniqueId from 'short-unique-id';
 
 export type LoginMethod = 'REDIRECT' | 'POPUP';
 
+/**
+ * Base configuration shared by all OAuth client implementations. Extended by
+ * {@link MsalClientConfig} and {@link AuthZeroClientConfig} with provider-specific options.
+ *
+ * See the security package README (`security/README.md`) for authentication architecture
+ * and setup guidance.
+ *
+ * @see BaseOAuthClient
+ */
 export interface BaseOAuthClientConfig<S extends AccessTokenSpec> {
     /** Client ID (GUID) of your app registered with your Oauth provider. */
     clientId: string;

package/security/authzero/AuthZeroClient.ts

@@ -15,6 +15,12 @@ import {mergeDeep, throwIf} from '@xh/hoist/utils/js';
 import {flatMap, union} from 'lodash';
 import {BaseOAuthClient, BaseOAuthClientConfig} from '../BaseOAuthClient';
 
+/**
+ * Configuration for an {@link AuthZeroClient} - the Auth0 OAuth client.
+ * Extends {@link BaseOAuthClientConfig} with Auth0-specific options.
+ *
+ * @see AuthZeroClient
+ */
 export interface AuthZeroClientConfig extends BaseOAuthClientConfig<AuthZeroTokenSpec> {
     /** Domain of your app registered with Auth0.  */
     domain: string;

package/security/msal/MsalClient.ts

@@ -23,6 +23,12 @@ import {flatMap, union, uniq} from 'lodash';
 import {BaseOAuthClient, BaseOAuthClientConfig} from '../BaseOAuthClient';
 import {AccessTokenSpec, TokenMap} from '../Types';
 
+/**
+ * Configuration for a {@link MsalClient} - the Microsoft Entra ID (Azure AD) OAuth client.
+ * Extends {@link BaseOAuthClientConfig} with MSAL-specific options.
+ *
+ * @see MsalClient
+ */
 export interface MsalClientConfig extends BaseOAuthClientConfig<MsalTokenSpec> {
     /**
      * Authority for your organization's tenant: `https://login.microsoftonline.com/[tenantId]`.

package/styles/vars.scss

@@ -575,6 +575,11 @@ body {
   --xh-grid-selected-row-text-color: var(--grid-selected-row-text-color, var(--xh-grid-text-color));
   --xh-grid-summary-row-border-color: var(--grid-summary-row-border-color, var(--xh-grid-border-color));
   --xh-grid-text-color: var(--grid-text-color, var(--xh-text-color));
+  --xh-grid-tooltip-bg: var(--grid-tooltip-bg, var(--xh-bg-alt));
+  --xh-grid-tooltip-border: var(--grid-tooltip-border, var(--xh-border-solid));
+  --xh-grid-tooltip-border-radius: var(--grid-tooltip-border-radius, var(--xh-border-radius-px));
+  --xh-grid-tooltip-max-width: var(--grid-tooltip-max-width, 400px);
+  --xh-grid-tooltip-padding: var(--grid-tooltip-padding, var(--xh-pad-half-px));
   --xh-grid-tree-indent: var(--grid-tree-indent, 1.2em);
   --xh-grid-tree-icon-px: var(--grid-tree-icon-px, 10px);
 
@@ -810,6 +815,15 @@ body {
   }
 
 
+  //------------------------
+  // Spinner
+  //------------------------
+  --xh-spinner-color: var(--spinner-color, #{mc('blue-grey', '400')});
+
+  &.xh-dark {
+    --xh-spinner-color: var(--spinner-color, var(--xh-blue-gray));
+  }
+
   //------------------------
   // Tabs
   //------------------------

package/svc/FetchService.ts

@@ -14,7 +14,7 @@ import {
     XH
 } from '@xh/hoist/core';
 import {Exception, HoistException, TimeoutException} from '@xh/hoist/exception';
-import {formatTraceparent, Span} from '@xh/hoist/utils/telemetry';
+import {formatTraceparent, Span, SpanConfig} from '@xh/hoist/utils/telemetry';
 import {PromiseTimeoutSpec} from '@xh/hoist/promise';
 import {isLocalDate, SECONDS} from '@xh/hoist/utils/datetime';
 import {apiDeprecated, warnIf} from '@xh/hoist/utils/js';
@@ -34,8 +34,8 @@ export interface FetchServiceDefaults {
 /**
  * Service for making managed HTTP requests, both to the app's own Hoist server and to remote APIs.
  *
- * Typically accessed via `XH.fetchService` or the convenience methods on XH — `XH.fetch()`,
- * `XH.fetchJson()`, `XH.postJson()`, `XH.putJson()`, `XH.deleteJson()` — which delegate here.
+ * Typically accessed via `XH.fetchService` or the convenience methods on XH - `XH.fetch()`,
+ * `XH.fetchJson()`, `XH.postJson()`, `XH.putJson()`, `XH.deleteJson()` - which delegate here.
  *
  * Wraps the standard Fetch API with CORS enabled, credentials included, and redirects followed.
  * Provides JSON convenience methods (`fetchJson`, `postJson`, `putJson`, `patchJson`,
@@ -197,9 +197,16 @@ export class FetchService extends HoistService {
     // Implementation
     //-----------------------
     private async fetchInternalAsync(opts: FetchOptions): Promise<any> {
+        // If a span spec provided create, wrap, and recurse
+        if (opts.span && !(opts.span instanceof Span)) {
+            return XH.traceService.withSpanAsync(opts.span, span =>
+                this.fetchInternalAsync({...opts, span})
+            );
+        }
+
         opts = this.withCorrelationId(opts);
 
-        // Tracing — create span for this request.
+        // Tracing - create span for this request.
         const span = this.startFetchSpan(opts);
         if (span) opts = {...opts, traceId: span.traceId};
 
@@ -219,7 +226,7 @@ export class FetchService extends HoistService {
             ret = ret.track({...trackOptions, correlationId: correlationId as string, loadSpec});
         }
 
-        // Tracing — end span on completion or failure.
+        // Tracing - end span on completion or failure.
         if (span) {
             ret = ret.then(
                 value => {
@@ -282,7 +289,9 @@ export class FetchService extends HoistService {
             'Content-Type': isPost ? 'application/x-www-form-urlencoded' : 'text/plain',
             ...defaultHeaders,
             ...(opts.asJson ? {Accept: 'application/json'} : {}),
-            ...(span ? {traceparent: formatTraceparent(span.traceId, span.spanId)} : {}),
+            ...(span
+                ? {traceparent: formatTraceparent(span.traceId, span.spanId, span.sampled)}
+                : {}),
             ...opts.headers
         };
 
@@ -418,13 +427,11 @@ export class FetchService extends HoistService {
         const method = opts.method ?? (opts.params ? 'POST' : 'GET'),
             url = this.extractUrlPath(opts.url);
 
-        if (url.endsWith('submitSpans')) return null;
-
         return traceService.createSpan({
             name: method,
             kind: 'client',
-            parent: opts.span,
-            tags: {'http.request.method': method, 'url.path': opts.url, source: 'hoist'},
+            parent: opts.span as Span,
+            tags: {'http.request.method': method, 'url.path': url, 'xh.source': 'hoist'},
             caller: this
         });
     }
@@ -455,7 +462,7 @@ export class FetchService extends HoistService {
         }
     }
 
-    private qsFilterFn = (prefix, value) => {
+    private qsFilterFn = (_prefix: string, value: any) => {
         if (isDate(value)) return value.getTime();
         if (isLocalDate(value)) return value.isoString;
         return value;
@@ -757,10 +764,12 @@ export interface FetchOptions {
     track?: string | TrackOptions;
 
     /**
-     * If set, the fetch span created by TraceService will be parented under this span.
-     * Use to nest fetch calls under a business-level span.
+     * Parent span for this fetch request. Use to nest fetch calls under a business-level span.
+     *
+     * Accepts an existing Span instance, a SpanConfig, or a string span name. When a SpanConfig or
+     * string is provided, FetchService will create and manage the parent span internally.
      */
-    span?: Span;
+    span?: Span | SpanConfig | string;
 
     /**
      * Distributed trace ID for this request. Set automatically by FetchService
@@ -787,7 +796,8 @@ export interface FetchException extends HoistException {
 
     /**
      * True if exception resulted from the fetch being aborted by fetchService, or the application.
-     * @see FetchService.abort and FetchOptions.autoAbortKey.
+     * @see FetchService.abort
+     * @see FetchOptions.autoAbortKey
      */
     isFetchAborted: boolean;
 }

package/svc/README.md

@@ -1,5 +1,17 @@
 # Services Package
 
+| Section | Description |
+|---------|-------------|
+| [Overview](#overview) | Purpose and principles of Hoist's built-in singleton services |
+| [Architecture](#architecture) | Service hierarchy, installation, and access via XH |
+| [Built-in Services](#built-in-services) | Reference for all 19 built-in services by category |
+| [Configuration Keys Reference](#configuration-keys-reference) | Soft config keys controlling service behavior |
+| [User Preference Keys Reference](#user-preference-keys-reference) | Per-user preference keys used by services |
+| [Creating Custom Services](#creating-custom-services) | How to create and install application services |
+| [Common Patterns](#common-patterns) | FetchService in loads, tracking, debounced search, WebSockets |
+| [Common Pitfalls](#common-pitfalls) | Fetch errors, native fetch, missing loadSpec, and more |
+| [Related Packages](#related-packages) | Links to core, cmp, promise, and admin packages |
+
 ## Overview
 
 The `/svc/` package contains Hoist's built-in singleton services - classes that provide app-wide
@@ -116,15 +128,16 @@ override async doLoadAsync(loadSpec: LoadSpec) {
 
 **Configuration Options:**
 
-| Option | Type | Description |
-|--------|------|-------------|
-| `url` | string | Request URL (relative URLs appended to `XH.baseUrl`) |
-| `body` | any | Request body |
-| `params` | object | Query string parameters |
-| `headers` | object | Additional headers |
-| `timeout` | number | Timeout in ms (default 30000) |
-| `autoAbortKey` | string | Cancel previous requests with same key |
-| `loadSpec` | LoadSpec | Metadata for tracking |
+| Option | Type | Description                                                                           |
+|--------|------|---------------------------------------------------------------------------------------|
+| `url` | string | Request URL (relative URLs appended to `XH.baseUrl`)                                  |
+| `body` | any | Request body                                                                          |
+| `params` | object | Query string parameters                                                               |
+| `headers` | object | Additional headers                                                                    |
+| `timeout` | number | Timeout in ms (default 30000)                                                         |
+| `autoAbortKey` | string | Cancel previous requests with same key                                                |
+| `loadSpec` | LoadSpec | Metadata for tracking                                                                 |
+| `span` | `Span \| string \| SpanConfig` | Parent span for tracing. Accepts an existing `Span`, a `SpanConfig`, or a string name |
 
 **App-Level Defaults (`FetchService.defaults`):**
 
@@ -303,6 +316,12 @@ Client-side distributed tracing — creates spans for user actions and fetch cal
 Hoist server. Exceptions thrown during traced operations include a `traceId` for correlation
 with server-side traces. Controlled by the `xhTraceConfig` soft config. Requires hoist-core 37+.
 
+Spans are sampled at creation time using `xhTraceConfig.sampleRules` — an ordered list of
+tag-matching rules with glob pattern support. Child spans inherit their parent's sampling
+decision. Unsampled spans are dropped before export unless they end in error and
+`alwaysSampleErrors` is enabled. The `traceparent` header propagates the sampling flag to
+the server. See the hoist-core tracing documentation for full sampling configuration details.
+
 ```typescript
 // Wrap an async operation in a span (from any HoistBase subclass)
 await this.withSpanAsync({name: 'loadPortfolio', caller: this}, async span => {
@@ -317,6 +336,17 @@ const result = this.withSpan({name: 'computeTotals', caller: this}, span => {
 
 // Simple string-only config
 await this.withSpanAsync('loadData', async span => { ... });
+
+// Nest a fetch call under a parent span without manual span management.
+// FetchService accepts a string, SpanConfig, or existing Span as the `span` option.
+const data = await XH.fetchJson({
+    url: 'api/portfolio',
+    span: 'loadPortfolio'
+});
+const data = await XH.fetchJson({
+    url: 'api/portfolio',
+    span: {name: 'loadPortfolio', tags: {portfolioId: id}, caller: this}
+});
 ```
 
 **SpanConfig:**