@xh/hoist 83.1.0 → 84.0.1

package/data/cube/aggregate/NullAggregator.ts

@@ -7,6 +7,7 @@
 
 import {Aggregator} from './Aggregator';
 
+/** Always returns null. Useful for fields that should not be aggregated. */
 export class NullAggregator extends Aggregator {
     override aggregate(rows, fieldName) {
         return null;

package/data/cube/aggregate/SingleAggregator.ts

@@ -7,6 +7,7 @@
 
 import {Aggregator} from './Aggregator';
 
+/** Returns the value if there is exactly one row, otherwise null. */
 export class SingleAggregator extends Aggregator {
     override aggregate(rows, fieldName) {
         return rows.length === 1 ? rows[0].data[fieldName] : null;

package/data/cube/aggregate/SumAggregator.ts

@@ -7,6 +7,7 @@
 
 import {Aggregator} from './Aggregator';
 
+/** Sums numeric values, skipping nulls. */
 export class SumAggregator extends Aggregator {
     override aggregate(rows, fieldName) {
         let ret = null;

package/data/cube/aggregate/SumStrictAggregator.ts

@@ -6,6 +6,7 @@
  */
 import {Aggregator} from './Aggregator';
 
+/** Sums numeric values, returning null if any value is null. */
 export class SumStrictAggregator extends Aggregator {
     override aggregate(rows, fieldName) {
         let ret = null;

package/data/cube/aggregate/UniqueAggregator.ts

@@ -7,6 +7,7 @@
 import {Aggregator} from './Aggregator';
 import {isEmpty, isEqual} from 'lodash';
 
+/** Returns the value if all rows share the same value, otherwise null. */
 export class UniqueAggregator extends Aggregator {
     override aggregate(rows, fieldName) {
         if (isEmpty(rows)) return null;

package/data/filter/BaseFilterFieldSpec.ts

@@ -9,6 +9,15 @@ import {Field, FieldFilter, FieldType, FilterValueSource, genDisplayName} from '
 import {compact, isArray, isEmpty} from 'lodash';
 import {FieldFilterOperator} from './Types';
 
+/**
+ * Base configuration for field-level filtering options - defines available operators, value
+ * enumeration, and display metadata. Not used directly by applications; extended by
+ * {@link GridFilterFieldSpecConfig} (for column-header filters via {@link GridFilterModelConfig})
+ * and {@link FilterChooserFieldSpecConfig} (for {@link FilterChooserModel}).
+ *
+ * @see GridFilterFieldSpec
+ * @see FilterChooserFieldSpec
+ */
 export interface BaseFilterFieldSpecConfig {
     /** Identifying field name to filter on. */
     field: string;

package/data/filter/Types.ts

@@ -13,6 +13,10 @@ export type FilterLike = Filter | FilterSpec | FilterTestFn | FilterLike[];
 
 export type FilterSpec = FieldFilterSpec | FunctionFilterSpec | CompoundFilterSpec;
 
+/**
+ * Plain-object form of a {@link FieldFilter} - a single field/operator/value condition.
+ * Can be passed anywhere a {@link FilterLike} is accepted.
+ */
 export interface FieldFilterSpec {
     /** Name of Field to filter or Field instance. */
     field: string | Field;
@@ -42,6 +46,10 @@ export type FieldFilterOperator =
     | 'includes'
     | 'excludes';
 
+/**
+ * Plain-object form of a {@link CompoundFilter} - a group of filters joined by AND/OR.
+ * Can be passed anywhere a {@link FilterLike} is accepted.
+ */
 export interface CompoundFilterSpec {
     /** Collection of Filters or configs to create. */
     filters: FilterLike[];
@@ -52,6 +60,10 @@ export interface CompoundFilterSpec {
 
 export type CompoundFilterOperator = 'AND' | 'OR' | 'and' | 'or';
 
+/**
+ * Plain-object form of a {@link FunctionFilter} - a custom function-based filter.
+ * Can be passed anywhere a {@link FilterLike} is accepted.
+ */
 export interface FunctionFilterSpec {
     /** Key used to identify this FunctionFilter.*/
     key: string;

package/desktop/README.md

@@ -1,5 +1,17 @@
 # Desktop Package
 
+| Section | Description |
+|---------|-------------|
+| [Overview](#overview) | Desktop platform, Blueprint foundation |
+| [Architecture](#architecture) | Directory structure and key sub-packages |
+| [Relationship to /cmp/](#relationship-to-cmp) | Platform-specific vs. cross-platform components |
+| [AppContainer](#appcontainer) | Desktop app shell and lifecycle |
+| [Component Sub-Packages](#component-sub-packages) | Panel, Toolbar, Button, Grid, Dashboard, Tabs, Inputs, and more |
+| [Dialogs](#dialogs) | Custom modal dialogs via Blueprint Kit export |
+| [Desktop Hooks](#desktop-hooks) | useContextMenu |
+| [Common Patterns](#common-patterns) | Blueprint wrappers, Popover, ContextMenu |
+| [Related Packages](#related-packages) | Links to cross-platform and utility packages |
+
 ## Overview
 
 The `/desktop/` package provides Hoist's desktop-specific UI components, incorporating the
@@ -169,20 +181,34 @@ covering toolbars, masks, collapse/resize, persistence, and modal support.
 
 ### Toolbar (`/cmp/toolbar/`)
 
-Container for action buttons and controls:
+Horizontal (or vertical) container for action buttons and controls. Toolbars are typically
+placed in a Panel's `tbar` (top) or `bbar` (bottom) slots. Use `filler()` to push items to
+the right side, and `'-'` (shortcut for `toolbarSep()`) for visual dividers.
 
 ```typescript
-import {toolbar, toolbarSep} from '@xh/hoist/desktop/cmp/toolbar';
+import {toolbar} from '@xh/hoist/desktop/cmp/toolbar';
+import {filler} from '@xh/hoist/cmp/layout';
 
-toolbar(
-    button({text: 'Add', icon: Icon.add()}),
-    button({text: 'Edit', icon: Icon.edit()}),
-    toolbarSep(),
-    filler(),
-    searchField()
-)
+toolbar({
+    items: [
+        button({text: 'Add', icon: Icon.add()}),
+        button({text: 'Edit', icon: Icon.edit()}),
+        '-',        // separator token — shorthand for toolbarSep()
+        filler(),
+        searchField()
+    ]
+})
 ```
 
+Key props:
+- `compact` - reduced height and font size (useful in dense UIs)
+- `vertical` - stack items vertically instead of horizontally
+- `enableOverflowMenu` - collapse items that don't fit into a dropdown menu
+- `collapseFrom` - `'start'` or `'end'` (default) for overflow direction
+- `minVisibleItems` - minimum items to keep visible before overflowing
+
+`Toolbar.defaults.compact` can be set at bootstrap for app-wide compact toolbars.
+
 ### Button (`/cmp/button/`)
 
 Desktop buttons with Blueprint styling:
@@ -340,6 +366,102 @@ leftRightChooser({model})
 | `/viewmanager/` | View save/load UI |
 | `/zoneGrid/` | Zone mapper for ZoneGrid columns |
 
+## Dialogs
+
+For simple alerts and confirmations, use the built-in `XH.message()` and `XH.confirm()` methods
+(see the [appcontainer README](../appcontainer/README.md#messages)).
+
+For custom dialogs with rich content (forms, grids, etc.), use the Blueprint `dialog` element
+factory from `@xh/hoist/kit/blueprint`. This is the standard Hoist pattern for modal dialogs -
+Blueprint's Dialog is re-exported through Kit with transitions disabled for snappy rendering.
+
+The typical pattern uses a dedicated model to manage the dialog's open/closed state and content,
+with the parent component always rendering the dialog component alongside its other children.
+The dialog renders as a Blueprint portal overlay when open and returns null when closed, so it
+can be included unconditionally in the parent's item list.
+
+```typescript
+// TaskDialogModel.ts - manages dialog open/closed state and form data
+export class TaskDialogModel extends HoistModel {
+    @observable isOpen = false;
+
+    @managed formModel = new FormModel({
+        fields: [{name: 'description', rules: [required]}]
+    });
+
+    @action
+    open(initialValues?) {
+        this.isOpen = true;
+        this.formModel.init(initialValues);
+    }
+
+    @action
+    close() { this.isOpen = false; }
+}
+
+// TaskDialog.ts - the dialog component, rendered by the parent
+export const taskDialog = hoistCmp.factory({
+    model: uses(TaskDialogModel),
+    render({model}) {
+        if (!model.isOpen) return null;
+        return dialog({
+            title: 'Edit Task',
+            style: {width: 500},
+            isOpen: true,
+            onClose: () => model.close(),
+            item: panel({
+                item: form(
+                    formField({field: 'description', item: textInput()})
+                ),
+                bbar: toolbar({
+                    items: [filler(), button({text: 'Save', intent: 'primary'})]
+                })
+            })
+        });
+    }
+});
+
+// TodoPanel.ts - the parent component that owns and renders the dialog
+export class TodoPanelModel extends HoistModel {
+    @managed taskDialogModel = new TaskDialogModel();
+    @managed gridModel = new GridModel({...});
+}
+
+export const todoPanel = hoistCmp.factory({
+    model: creates(TodoPanelModel),
+    render({model}) {
+        return panel({
+            tbar: toolbar({
+                items: [
+                    button({
+                        text: 'New Task',
+                        icon: Icon.add(),
+                        onClick: () => model.taskDialogModel.open()
+                    })
+                ]
+            }),
+            items: [
+                grid(),
+                taskDialog()   // Always rendered - shows/hides based on isOpen
+            ]
+        });
+    }
+});
+```
+
+Key points:
+- Import `dialog` from `@xh/hoist/kit/blueprint` (not from Blueprint directly) to get
+  Hoist's transition-disabled wrapper.
+- The parent model owns the dialog model as a `@managed` property and calls `open()`/`close()`.
+- The parent component renders the dialog factory in its `items` alongside other children -
+  the dialog shows/hides itself based on its model's `isOpen` state.
+- Use `onClose` to handle the dialog's close button and outside-click-to-close.
+- Wrap dialog content in a `panel()` when you need toolbars, masks, or standard layout.
+
+Note: Hoist does not yet provide its own first-class Dialog component wrapper
+([#861](https://github.com/xh/hoist-react/issues/861)) - the Blueprint Kit re-export is the
+established pattern used throughout the framework and applications.
+
 ## Desktop Hooks
 
 ### useContextMenu

package/desktop/appcontainer/AboutDialog.ts

@@ -45,6 +45,7 @@ export const aboutDialog = hoistCmp.factory({
                     button({
                         text: 'Send Client Health Report',
                         icon: Icon.health(),
+                        testId: 'xh-about-health-report-btn',
                         omit: !XH.clientHealthService.enabled,
                         onClick: async () => {
                             try {
@@ -60,6 +61,7 @@ export const aboutDialog = hoistCmp.factory({
                         text: 'Close',
                         intent: 'primary',
                         outlined: true,
+                        testId: 'xh-about-close-btn',
                         onClick: onClose
                     })
                 )

package/desktop/appcontainer/Banner.ts

@@ -26,9 +26,10 @@ export const banner = hoistCmp.factory({
     model: uses(BannerModel),
 
     render({model}) {
-        const {icon, message, intent, onClick, className} = model;
+        const {icon, message, intent, onClick, className, category} = model;
 
         return toolbar({
+            testId: `xh-banner-${category}`,
             className: classNames(
                 'xh-banner',
                 className,
@@ -57,12 +58,13 @@ export const banner = hoistCmp.factory({
 });
 
 const actionButton = hoistCmp.factory<BannerModel>(({model}) => {
-    const {actionButtonProps} = model;
+    const {actionButtonProps, category} = model;
     if (isEmpty(actionButtonProps)) return null;
 
     return button({
         outlined: true,
         className: 'xh-banner__action-button',
+        testId: `xh-banner-${category}-action-btn`,
         ...actionButtonProps
     });
 });
@@ -74,6 +76,7 @@ const dismissButton = hoistCmp.factory<BannerModel>(({model}) => {
     return button({
         icon: Icon.close(),
         className: 'xh-banner__dismiss-button',
+        testId: `xh-banner-${category}-dismiss-btn`,
         onClick: () => {
             XH.hideBanner(category);
             if (isFunction(onClose)) onClose(model);

package/desktop/appcontainer/ChangelogDialog.ts

@@ -44,6 +44,7 @@ const changelogContents = hoistCmp.factory<ChangelogDialogModel>(({model}) => {
             button({
                 text: 'Close',
                 intent: 'primary',
+                testId: 'xh-changelog-close-btn',
                 onClick: () => model.hide()
             })
         ]

package/desktop/appcontainer/ExceptionDialog.ts

@@ -62,12 +62,14 @@ const bbar = hoistCmp.factory<ExceptionDialogModel>(({model}) =>
             omit: !XH.identityService?.isImpersonating,
             icon: Icon.impersonate(),
             text: 'End Impersonation',
+            testId: 'xh-exception-end-impersonation-btn',
             onClick: () => XH.identityService.endImpersonateAsync()
         }),
         filler(),
         button({
             icon: Icon.search(),
             text: 'Show/Report Details',
+            testId: 'xh-exception-details-btn',
             onClick: () => model.openDetails(),
             omit: !model.options.showAsError
         }),
@@ -86,11 +88,13 @@ export const dismissButton = hoistCmp.factory<ExceptionDialogModel>(({model}) =>
         ? button({
               icon: Icon.refresh(),
               text: 'Reload App',
+              testId: 'xh-exception-dismiss-btn',
               autoFocus: true,
               onClick: () => XH.reloadApp({removeQueryParams: true})
           })
         : button({
               text: 'Close',
+              testId: 'xh-exception-dismiss-btn',
               autoFocus: true,
               onClick: () => model.close()
           });

package/desktop/appcontainer/ExceptionDialogDetails.ts

@@ -62,6 +62,7 @@ export const exceptionDialogDetails = hoistCmp.factory<ExceptionDialogModel>(({m
                         placeholder: 'Add message here...',
                         width: '100%',
                         height: 120,
+                        testId: 'xh-exception-details-message',
                         omit: !clientUserKnown
                     })
                 ]
@@ -71,13 +72,15 @@ export const exceptionDialogDetails = hoistCmp.factory<ExceptionDialogModel>(({m
                 button({
                     icon: Icon.envelope(),
                     text: 'Send',
+                    testId: 'xh-exception-details-send-btn',
                     disabled: !model.userMessage,
                     onClick: () => model.sendReportAsync(),
                     omit: !clientUserKnown
                 }),
                 clipboardButton({
                     getCopyText: () => errorStr,
-                    successMessage: 'Error details copied to clipboard.'
+                    successMessage: 'Error details copied to clipboard.',
+                    testId: 'xh-exception-details-copy-btn'
                 }),
                 dismissButton()
             ])

package/desktop/appcontainer/FeedbackDialog.ts

@@ -37,12 +37,14 @@ export const feedbackDialog = hoistCmp.factory({
                     height: 250,
                     style: {marginBottom: 2},
                     commitOnChange: true,
-                    bind: 'message'
+                    bind: 'message',
+                    testId: 'xh-feedback-message'
                 }),
                 toolbar(
                     filler(),
                     button({
                         text: 'Cancel',
+                        testId: 'xh-feedback-cancel-btn',
                         onClick: () => model.hide()
                     }),
                     button({
@@ -50,6 +52,7 @@ export const feedbackDialog = hoistCmp.factory({
                         intent: 'success',
                         minimal: false,
                         disabled: !model.message,
+                        testId: 'xh-feedback-send-btn',
                         onClick: () => model.submitAsync()
                     })
                 )

package/desktop/appcontainer/ImpersonationBar.ts

@@ -41,6 +41,7 @@ export const impersonationBar = hoistCmp.factory({
 
         return toolbar({
             className: 'xh-impersonation-bar',
+            testId: 'xh-impersonation-bar',
             items: [
                 Icon.impersonate(),
                 span(msg),
@@ -49,6 +50,7 @@ export const impersonationBar = hoistCmp.factory({
                     text: 'Important Reminders',
                     icon: Icon.warning(),
                     outlined: true,
+                    testId: 'xh-impersonation-reminders-btn',
                     onClick: showUseResponsiblyAlert
                 }),
                 hspacer(),
@@ -64,12 +66,14 @@ export const impersonationBar = hoistCmp.factory({
                     maxWidth: 350,
                     menuWidth: 350,
                     flex: 1,
+                    testId: 'xh-impersonation-target',
                     onCommit: model.onCommit,
                     ref: model.inputRef
                 }),
                 button({
                     text: isImpersonating ? 'Exit Impersonation' : 'Cancel',
                     outlined: true,
+                    testId: 'xh-impersonation-exit-btn',
                     onClick: model.onClose
                 })
             ]

package/desktop/appcontainer/LockoutPanel.ts

@@ -27,6 +27,7 @@ export const lockoutPanel = hoistCmp.factory({
                 filler(),
                 box({
                     className: 'xh-lockout-panel',
+                    testId: 'xh-lockout-panel',
                     item: unauthorizedMessage()
                 }),
                 filler()
@@ -60,7 +61,8 @@ const unauthorizedMessage = hoistCmp.factory<AppContainerModel>({
                 logoutButton({
                     text: 'Logout',
                     intent: null,
-                    minimal: false
+                    minimal: false,
+                    testId: 'xh-lockout-logout-btn'
                 }),
                 hspacer(5),
                 button({
@@ -68,6 +70,7 @@ const unauthorizedMessage = hoistCmp.factory<AppContainerModel>({
                     icon: Icon.impersonate(),
                     text: 'End Impersonation',
                     minimal: false,
+                    testId: 'xh-lockout-end-impersonation-btn',
                     onClick: () => identityService.endImpersonateAsync()
                 }),
                 filler()

package/desktop/appcontainer/LoginPanel.ts

@@ -39,6 +39,7 @@ export const loginPanel = hoistCmp.factory({
                 title: XH.clientAppName,
                 icon: Icon.login(),
                 className: 'xh-login',
+                testId: 'xh-login',
                 width: 300,
                 mask: loadObserver,
                 items: [
@@ -51,7 +52,8 @@ export const loginPanel = hoistCmp.factory({
                             autoFocus: true,
                             commitOnChange: true,
                             onKeyDown,
-                            width: null
+                            width: null,
+                            testId: 'xh-login-username'
                         }),
                         textInput({
                             bind: 'password',
@@ -60,7 +62,8 @@ export const loginPanel = hoistCmp.factory({
                             type: 'password',
                             commitOnChange: true,
                             onKeyDown,
-                            width: null
+                            width: null,
+                            testId: 'xh-login-password'
                         })
                     ),
                     div({
@@ -81,7 +84,8 @@ export const loginPanel = hoistCmp.factory({
                         intent: 'primary',
                         icon: Icon.login(),
                         disabled: !isValid || loginInProgress,
-                        onClick: () => model.submitAsync()
+                        onClick: () => model.submitAsync(),
+                        testId: 'xh-login-btn'
                     })
                 ]
             })

package/desktop/appcontainer/Message.ts

@@ -52,6 +52,7 @@ const inputsCmp = hoistCmp.factory<MessageModel>(({model}) => {
             formField({
                 field: 'value',
                 label: null,
+                testId: 'xh-message-value',
                 item: withDefault(
                     input.item,
                     textInput({
@@ -70,6 +71,7 @@ const inputsCmp = hoistCmp.factory<MessageModel>(({model}) => {
             formField({
                 label: extraConfirmLabel,
                 field: 'extraConfirm',
+                testId: 'xh-message-extra-confirm',
                 item: textInput({
                     autoFocus: true,
                     selectOnFocus: true,
@@ -95,7 +97,7 @@ const bbar = hoistCmp.factory<MessageModel>(({model}) => {
         ret = [];
 
     if (cancelProps) {
-        ret.push(button(cancelProps));
+        ret.push(button({testId: 'xh-message-cancel-btn', ...cancelProps}));
     }
 
     if (cancelAlign === 'left') {
@@ -108,8 +110,12 @@ const bbar = hoistCmp.factory<MessageModel>(({model}) => {
         // Merge in formModel.isValid here in render stage to get reactivity.
         ret.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})
         );
     }
 

package/desktop/appcontainer/OptionsDialog.ts

@@ -51,10 +51,11 @@ export const optionsDialog = hoistCmp.factory({
                         })
                     ),
                     bbar: [
-                        restoreDefaultsButton(),
+                        restoreDefaultsButton({testId: 'xh-options-restore-defaults-btn'}),
                         filler(),
                         button({
                             text: 'Cancel',
+                            testId: 'xh-options-cancel-btn',
                             onClick: () => model.hide()
                         }),
                         button({
@@ -62,6 +63,7 @@ export const optionsDialog = hoistCmp.factory({
                             text: reloadRequired ? 'Save & Reload' : 'Save',
                             icon: reloadRequired ? Icon.refresh() : Icon.check(),
                             intent: 'success',
+                            testId: 'xh-options-save-btn',
                             onClick: () => model.saveAsync()
                         })
                     ]

package/desktop/appcontainer/VersionBar.ts

@@ -26,6 +26,7 @@ export const versionBar = hoistCmp.factory({
 
         return box({
             className: `xh-version-bar xh-version-bar--${env.toLowerCase()}`,
+            testId: 'xh-version-bar',
             items: [
                 [XH.appName, env, versionAndBuild].join(' • '),
                 span({

package/desktop/appcontainer/suspend/IdlePanel.ts

@@ -4,14 +4,12 @@
  *
  * Copyright © 2026 Extremely Heavy Industries Inc.
  */
+import {div, filler, img, p, viewport} from '@xh/hoist/cmp/layout';
 import {hoistCmp, XH} from '@xh/hoist/core';
-import {viewport, div, img, p, filler} from '@xh/hoist/cmp/layout';
-import {panel} from '@xh/hoist/desktop/cmp/panel';
 import {button} from '@xh/hoist/desktop/cmp/button';
+import {panel} from '@xh/hoist/desktop/cmp/panel';
 import {Icon} from '@xh/hoist/icon';
-
 import './IdlePanel.scss';
-// @ts-ignore
 import idleImage from './IdlePanelImage.png';
 
 /**
@@ -33,6 +31,7 @@ export const idlePanel = hoistCmp.factory({
                 title: `${XH.clientAppName} is sleeping`,
                 icon: Icon.moon(),
                 className: 'xh-idle-panel',
+                testId: 'xh-idle-panel',
                 item: div(
                     img({
                         src: idleImage,
@@ -49,6 +48,7 @@ export const idlePanel = hoistCmp.factory({
                         intent: 'primary',
                         minimal: false,
                         autoFocus: true,
+                        testId: 'xh-idle-reactivate-btn',
                         onClick: onReactivate
                     })
                 ]

package/desktop/appcontainer/suspend/SuspendPanel.ts

@@ -59,6 +59,7 @@ export const suspendPanel = hoistCmp.factory<AppContainerModel>({
                 title,
                 icon,
                 className: 'xh-suspend-panel',
+                testId: 'xh-suspend-panel',
                 item: div({
                     className: 'xh-suspend-panel__inner',
                     items: [
@@ -71,6 +72,7 @@ export const suspendPanel = hoistCmp.factory<AppContainerModel>({
                         text: 'More Details',
                         icon: Icon.detail(),
                         minimal: true,
+                        testId: 'xh-suspend-details-btn',
                         omit: !exception,
                         onClick: () => XH.exceptionHandler.showExceptionDetails(exception)
                     }),
@@ -81,6 +83,7 @@ export const suspendPanel = hoistCmp.factory<AppContainerModel>({
                         intent: 'primary',
                         minimal: false,
                         autoFocus: true,
+                        testId: 'xh-suspend-reload-btn',
                         onClick: () => XH.reloadApp()
                     })
                 ]

package/desktop/cmp/button/AppMenuButton.ts

@@ -64,6 +64,11 @@ export interface AppMenuButtonProps extends ButtonProps {
 
 type RenderWithUserProfileCustomFn = (user: HoistUser) => ReactNode;
 
+/**
+ * Application-level menu button rendered in the AppBar. Provides a dropdown menu with standard
+ * items for About, Admin, Feedback, Options, Theme, Impersonation, Changelog, and Logout.
+ * Individual items can be hidden via props, and custom items added via `extraItems`.
+ */
 export const [AppMenuButton, appMenuButton] = hoistCmp.withFactory<AppMenuButtonProps>({
     displayName: 'AppMenuButton',
     model: false,