@xh/hoist 86.1.0 → 86.3.0

package/build/types/mobile/cmp/input/NumberInput.d.ts

@@ -26,7 +26,7 @@ export interface NumberInputProps extends HoistProps, HoistInputProps, StyleProp
     modifier?: string;
     /** Text to display when control is empty. */
     placeholder?: string;
-    /** Max decimal precision of the value, defaults to 4. */
+    /** Max decimal precision of the value, defaults to 4. Set to null for full, unrestricted precision. */
     precision?: NumericPrecision;
     /**
      * Scale factor to apply when converting between the internal and external value. Useful for

package/build/types/mobile/cmp/input/Select.d.ts

@@ -109,6 +109,14 @@ export interface SelectProps extends HoistProps, HoistInputProps, LayoutProps {
     title?: string;
     /** Field on provided options for sourcing each option's value (default `value`). */
     valueField?: string;
+    /**
+     * Function to generate a `SelectOption` for a (non-null) selected value not present in the
+     * current options list. Return null to fall back to the default value-as-label behavior.
+     *
+     * Useful with queryFn-based selects, readonly forms, or any case where options may not be
+     * loaded when a value is set, ensuring the value renders with its proper label.
+     */
+    generateOptionFn?: (value: any) => SelectOption;
 }
 /**
  * A managed wrapper around the React-Select combobox/dropdown component.

package/cmp/grid/Grid.ts

@@ -48,6 +48,8 @@ import {consumeEvent, isDisplayed, logWithDebug} from '@xh/hoist/utils/js';
 import {composeRefs, createObservableRef, getLayoutProps} from '@xh/hoist/utils/react';
 import classNames from 'classnames';
 import {compact, debounce, isBoolean, isEmpty, isEqual, isNil, max, maxBy, merge} from 'lodash';
+import {type MouseEvent} from 'react';
+import {PartialDeep} from 'type-fest';
 import './Grid.scss';
 import {GridModel} from './GridModel';
 import {columnGroupHeader} from './impl/ColumnGroupHeader';
@@ -65,7 +67,7 @@ export interface GridProps<M extends GridModel = GridModel>
      *
      * Note that changes to these options after the component's initial render will be ignored.
      */
-    agOptions?: GridOptions;
+    agOptions?: PartialDeep<GridOptions>;
 
     /**
      * Callback when the grid has initialized. The component will call this with the ag-Grid
@@ -135,6 +137,7 @@ export const [Grid, grid] = hoistCmp.withFactory<GridProps>({
                 ],
                 testId,
                 onKeyDown: impl.onKeyDown,
+                onMouseDown: impl.onViewMouseDown,
                 ref: composeRefs(impl.viewRef, model.viewRef, ref)
             }),
             colChooserModel ? platformColChooser({model: colChooserModel}) : null,
@@ -151,6 +154,10 @@ export const [Grid, grid] = hoistCmp.withFactory<GridProps>({
 export class GridLocalModel extends HoistModel {
     override xhImpl = true;
 
+    // Structural "empty" grid space.
+    private static EMPTY_SPACE_SELECTOR =
+        '.ag-body-viewport, .ag-center-cols-viewport, .ag-center-cols-container, .ag-row';
+
     @lookup(GridModel)
     private model: GridModel;
     agOptions: GridOptions;
@@ -386,7 +393,14 @@ export class GridLocalModel extends HoistModel {
         return {
             track: () => [model.agApi, model.groupBy],
             run: ([agApi, groupBy]) => {
-                if (agApi) agApi.setRowGroupColumns(groupBy);
+                if (!agApi) return;
+                agApi.setRowGroupColumns(groupBy);
+
+                // Re-assert configured visibility - AG Grid re-shows a column when ungrouped (#4473).
+                const state = model.columnState
+                    .filter(({colId}) => !groupBy.includes(colId))
+                    .map(({colId, hidden}) => ({colId, hide: hidden}));
+                agApi.applyColumnState({state});
             }
         };
     }
@@ -844,6 +858,17 @@ export class GridLocalModel extends HoistModel {
         return this.rowKeyNavSupport?.navigateToNextCell(agParams);
     };
 
+    // `stopEditingWhenCellsLoseFocus` doesn't fire on clicks in empty grid space (focus stays in
+    // the grid), so commit the active edit on those clicks ourselves. Require exact match on empty
+    // space to avoid interfering with cell editors.
+    onViewMouseDown = (evt: MouseEvent) => {
+        const {model} = this,
+            target = evt.target as HTMLElement;
+        if (model.isEditing && target.matches(GridLocalModel.EMPTY_SPACE_SELECTOR)) {
+            model.agApi?.stopEditing();
+        }
+    };
+
     onCellMouseDown = evt => {
         const {model} = this;
         if (model.highlightRowOnClick) {

package/cmp/grid/GridModel.ts

@@ -16,6 +16,7 @@ import {
     GridAutosizeMode,
     GridFilterModelConfig,
     GridGroupSortFn,
+    IColChooserModel,
     isColumnSpec,
     TreeStyle
 } from '@xh/hoist/cmp/grid';
@@ -305,6 +306,10 @@ export interface GridConfig {
      * expand/collapse options in the default context menu will be enhanced to allow users to
      * expand/collapse to a specific level. See {@link GroupingChooserModel.valueDisplayNames}
      * for a convenient getter that will satisfy this API when a GroupingChooser is in play.
+     *
+     * Labels are matched to levels top-down and need not cover the full depth of the grid - provide
+     * a partial array to label only the top levels (e.g. when deeper levels should not be
+     * expand-to targets). Deeper, unlabelled levels are omitted from the menu.
      */
     levelLabels?: Thunkable<string[]>;
 
@@ -494,7 +499,7 @@ export class GridModel extends HoistModel {
     store: Store;
     selModel: StoreSelectionModel;
     treeMode: boolean;
-    colChooserModel: HoistModel;
+    colChooserModel: IColChooserModel;
     rowClassFn: RowClassFn;
     rowClassRules: Record<string, RowClassRuleFn>;
     contextMenu: GridContextMenuSpec;
@@ -1174,15 +1179,23 @@ export class GridModel extends HoistModel {
 
     /**
      * Get the resolved level labels for the current state of the grid.
+     * An over-long array is truncated to the current `maxDepth`.
      */
     get resolvedLevelLabels(): string[] {
         const {maxDepth, levelLabels} = this,
             ret = executeIfFunction(levelLabels);
-        if (ret && ret.length < maxDepth + 1) {
-            this.logDebug('Value produced by `GridModel.levelLabels` has insufficient length.');
-            return null;
-        }
-        return ret ? take(ret, maxDepth + 1) : null;
+        return !isEmpty(ret) ? take(ret, maxDepth + 1) : null;
+    }
+
+    /**
+     * True if the given `resolvedLevelLabels` index is the grid's current expand level - used to
+     * mark the active item in the "Expand to..." menu. The deepest labelled level counts as current
+     * whenever the grid is expanded to or beyond it.
+     */
+    isCurrentExpandLevel(idx: number): boolean {
+        const {expandLevel, resolvedLevelLabels} = this,
+            lastIdx = resolvedLevelLabels?.length - 1;
+        return expandLevel === idx || (idx === lastIdx && expandLevel > lastIdx);
     }
 
     /**
@@ -1247,7 +1260,7 @@ export class GridModel extends HoistModel {
     }
 
     showColChooser() {
-        (this.colChooserModel as any)?.open();
+        this.colChooserModel?.open();
     }
 
     noteAgColumnStateChanged(agColState: AgColumnState[]) {
@@ -1974,7 +1987,7 @@ export class GridModel extends HoistModel {
         };
     }
 
-    private parseChooserModel(chooserModel: GridConfig['colChooserModel']): HoistModel {
+    private parseChooserModel(chooserModel: GridConfig['colChooserModel']): IColChooserModel {
         if (!chooserModel) return null;
 
         const modelClass = XH.isMobileApp ? MobileColChooserModel : DesktopColChooserModel;

package/cmp/grid/Types.ts

@@ -5,7 +5,7 @@
  * Copyright © 2026 Extremely Heavy Industries Inc.
  */
 
-import type {HSide, PersistOptions, Some} from '@xh/hoist/core';
+import type {HoistModel, HSide, PersistOptions, Some} from '@xh/hoist/core';
 import type {
     FilterBindTarget,
     FilterMatchMode,
@@ -142,6 +142,14 @@ export interface GridFilterBindTarget extends FilterBindTarget, FilterValueSourc
  */
 export type GroupRowRenderer = (context: ICellRendererParams) => ReactNode;
 
+/** Cross-platform interface for desktop and mobile ColChooserModels. */
+export interface IColChooserModel extends HoistModel {
+    readonly gridModel: GridModel;
+    readonly isOpen: boolean;
+    open(): void;
+    close(): void;
+}
+
 /**
  * Configuration for a {@link ColChooserModel} - the model backing the grid column chooser UI.
  * Passed via the `colChooserModel` config on {@link GridConfig}, or set app-wide via

package/cmp/grid/filter/GridFilterFieldSpec.ts

@@ -4,7 +4,6 @@
  *
  * Copyright © 2026 Extremely Heavy Industries Inc.
  */
-import {ColumnRenderer} from '@xh/hoist/cmp/grid';
 import {HoistInputProps} from '@xh/hoist/cmp/input';
 import {PlainObject} from '@xh/hoist/core';
 import {
@@ -19,17 +18,38 @@ import {
     BaseFilterFieldSpecConfig
 } from '@xh/hoist/data/filter/BaseFilterFieldSpec';
 import {castArray, compact, flatMap, isDate, isEmpty, uniqBy} from 'lodash';
+import {ReactNode} from 'react';
 import {GridFilterModel} from './GridFilterModel';
 
+/**
+ * Produces the display content for an entry in the Values tab of a column filter. Must be a pure
+ * transform of the value - the values list carries no source record, and there is no column or
+ * grid context to reach for (unlike a Column's `renderer`, which runs against the source grid).
+ */
+export type GridFilterRenderer = (value: any) => ReactNode;
+
+/**
+ * Produces the value to sort by for an entry in the Values tab of a column filter. Must be a pure
+ * transform of the value - the values list carries no source record, and there is no column or
+ * grid context to reach for (unlike a Column's `sortValue`, which runs against the source grid).
+ */
+export type GridFilterSortValueFn = (value: any) => any;
+
 export interface GridFilterFieldSpecConfig extends BaseFilterFieldSpecConfig {
     /** GridFilterModel instance owning this fieldSpec. */
     filterModel?: GridFilterModel;
 
     /**
-     * Function returning a formatted string for each value in this values filter display.
-     * If not provided, the Column's renderer will be used.
+     * Pure function producing the display content for each entry in the values filter display. If
+     * not provided, the Column's renderer is used where it can be applied to a bare value.
+     */
+    renderer?: GridFilterRenderer;
+
+    /**
+     * Pure function producing the value to sort each entry of the values filter display by. If not
+     * provided, the Column's sortValue is used where it can be applied to a bare value.
      */
-    renderer?: ColumnRenderer;
+    sortValue?: GridFilterSortValueFn;
 
     /**
      * Props to pass through to the HoistInput components used on the custom filter tab.
@@ -47,7 +67,8 @@ export interface GridFilterFieldSpecConfig extends BaseFilterFieldSpecConfig {
  */
 export class GridFilterFieldSpec extends BaseFilterFieldSpec {
     filterModel: GridFilterModel;
-    renderer: ColumnRenderer;
+    renderer: GridFilterRenderer;
+    sortValue: GridFilterSortValueFn;
     inputProps: PlainObject;
     defaultOp: FieldFilterOperator;
 
@@ -57,6 +78,7 @@ export class GridFilterFieldSpec extends BaseFilterFieldSpec {
     constructor({
         filterModel,
         renderer,
+        sortValue,
         inputProps,
         defaultOp,
         ...rest
@@ -65,6 +87,7 @@ export class GridFilterFieldSpec extends BaseFilterFieldSpec {
 
         this.filterModel = filterModel;
         this.renderer = renderer;
+        this.sortValue = sortValue;
         this.inputProps = inputProps;
         this.defaultOp = this.ops.includes(defaultOp) ? defaultOp : this.ops[0];
     }

package/cmp/grid/impl/MenuSupport.ts

@@ -138,7 +138,7 @@ function replaceHoistToken(token: string, gridModel: GridModel): Some<RecordActi
                 text: 'Columns...',
                 icon: Icon.gridPanel(),
                 hidden: !gridModel?.colChooserModel,
-                actionFn: () => (gridModel.colChooserModel as any)?.open()
+                actionFn: () => gridModel.colChooserModel?.open()
             });
         case 'expandCollapseAll': // For backward compatibility
         case 'expandCollapse':
@@ -280,15 +280,13 @@ function levelExpandAction(gridModel: GridModel): RecordAction {
     return new RecordAction({
         text: 'Expand to...',
         displayFn: () => {
-            const {maxDepth, expandLevel, resolvedLevelLabels} = gridModel;
+            const {maxDepth, resolvedLevelLabels} = gridModel;
 
             // Don't show for flat grid models or if we don't have labels
             if (!maxDepth || !resolvedLevelLabels) return {hidden: true};
 
             const items = resolvedLevelLabels.map((label, idx) => {
-                const isCurrLevel =
-                    expandLevel === idx ||
-                    (expandLevel > maxDepth && idx === resolvedLevelLabels.length - 1);
+                const isCurrLevel = gridModel.isCurrentExpandLevel(idx);
 
                 return {
                     icon: isCurrLevel ? Icon.check() : null,

package/cmp/input/SegmentedControlOption.ts

@@ -33,6 +33,13 @@ export interface SegmentedControlOption {
      * `intent` default. Defaults to the control's `intent`.
      */
     intent?: Intent;
+
+    /**
+     * Optional stable identifier emitted on this option's rendered button as `data-testid`, for
+     * use by E2E tests. If omitted and the control itself has a `testId`, one is auto-derived as
+     * `${controlTestId}-${value}`. If neither is set, no attribute is emitted.
+     */
+    testId?: string;
 }
 
 /**
@@ -58,4 +65,11 @@ export interface SegmentedControlNullOption {
      * `intent` default. Defaults to the control's `intent`.
      */
     intent?: Intent;
+
+    /**
+     * Optional stable identifier emitted on this option's rendered button as `data-testid`, for
+     * use by E2E tests. If omitted and the control itself has a `testId`, one is auto-derived as
+     * `${controlTestId}-null`. If neither is set, no attribute is emitted.
+     */
+    testId?: string;
 }

package/cmp/store/impl/StoreFilterFieldImplModel.ts

@@ -66,7 +66,7 @@ export class StoreFilterFieldImplModel extends HoistModel {
 
         this.addReaction(
             {
-                track: () => [this.filterText, gridModel?.columns, gridModel?.groupBy],
+                track: () => [this.filterText, gridModel?.columns],
                 run: () => this.regenerateFilter(),
                 fireImmediately: true
             },
@@ -161,8 +161,7 @@ export class StoreFilterFieldImplModel extends HoistModel {
         if (excludeFields) ret = without(ret, ...excludeFields);
 
         if (gridModel) {
-            const groupBy = gridModel.groupBy,
-                visibleCols = gridModel.getVisibleLeafColumns();
+            const visibleCols = gridModel.getVisibleLeafColumns();
 
             // Push on dot-delimited grid column fields. These are supported by Grid and traverse
             // sub-objects in StoreRecord.data to display nested properties. Given that Grid treats these
@@ -182,12 +181,12 @@ export class StoreFilterFieldImplModel extends HoistModel {
             // Run exclude once more to support explicitly excluding a dot-sep field added above.
             if (excludeFields) ret = without(ret, ...excludeFields);
 
-            // Final filter for column visibility, or explicit request for inclusion.
+            // Final filter for column visibility, or explicit request for inclusion. Deliberately
+            // not keyed to groupBy, so filter results stay stable across regrouping (see #4070).
             ret = ret.filter(f => {
                 return (
                     (includeFields && includeFields.includes(f)) ||
-                    visibleCols.find(c => c.field === f) ||
-                    groupBy.includes(f)
+                    visibleCols.find(c => c.field === f)
                 );
             });
         }

package/core/HoistAppModel.ts

@@ -5,8 +5,7 @@
  * Copyright © 2026 Extremely Heavy Industries Inc.
  */
 import {webSocketIndicator} from '@xh/hoist/cmp/websocket';
-import {AppOptionSpec, HoistModel, InitContext, Thunkable} from './';
-import {Route} from 'router5';
+import {AppOptionSpec, HoistModel, HoistRoute, InitContext, Thunkable} from './';
 import {ReactNode} from 'react';
 /**
  * Specialized base class for defining the central model for a Hoist app as specified by its
@@ -52,7 +51,7 @@ export class HoistAppModel extends HoistModel {
     /**
      * Provide the initial set of Router5 Routes to be used by this application.
      */
-    getRoutes(): Route[] {
+    getRoutes(): HoistRoute[] {
         return [];
     }
 

package/core/types/Types.ts

@@ -9,6 +9,7 @@ import {LocalDate} from '@xh/hoist/utils/datetime';
 import {MomentInput} from 'moment';
 import {Component, FunctionComponent, ReactElement} from 'react';
 import {DebounceSettings} from 'lodash';
+import {Route} from 'router5';
 
 /** Values available for intents. */
 export type Intent = 'primary' | 'success' | 'warning' | 'danger';
@@ -55,14 +56,22 @@ export type DebounceSpec = number | (DebounceSettings & {interval: number});
  * function that returns a ReactElement. In either case, the function will be called with no arguments.
  */
 export type Content =
-    | ReactElement
-    | FunctionComponent
-    | Component
-    | ElementFactory
-    | (() => ReactElement);
+    ReactElement | FunctionComponent | Component | ElementFactory | (() => ReactElement);
 
 export type DateLike = Date | LocalDate | MomentInput;
 
+/**
+ * A Router5 {@link Route} spec, extended with Hoist's `omit` support for declarative exclusion of
+ * routes at registration time (e.g. role-gated sections). Note `omit` is evaluated once when routes
+ * are added to the router during app startup - it is not reactive.
+ *
+ * @see HoistAppModel.getRoutes
+ */
+export interface HoistRoute extends Omit<Route, 'children'> {
+    omit?: Thunkable<boolean>;
+    children?: HoistRoute[];
+}
+
 /** Valid units for the {@link LocalDate} adjustment methods. */
 export type LocalDateUnit =
     | 'year'

package/desktop/cmp/button/grid/ExpandToLevelButton.ts

@@ -28,7 +28,8 @@ export interface ExpandToLevelButtonProps extends Omit<ButtonProps, 'title'> {
 
 /**
  * A menu button to expand a multi-level grouped or tree grid out to a desired level.
- * Requires {@link GridConfig.levelLabels} to be configured on the bound GridModel.
+ * Requires {@link GridConfig.levelLabels} to be configured on the bound GridModel - the menu offers
+ * one entry per labelled level, so a partial array will limit the available expand-to targets.
  */
 export const [ExpandToLevelButton, expandToLevelButton] =
     hoistCmp.withFactory<ExpandToLevelButtonProps>({
@@ -53,13 +54,11 @@ export const [ExpandToLevelButton, expandToLevelButton] =
             }
 
             // Render a disabled button if requested, if we have a flat grid, or no level labels
-            const {maxDepth, expandLevel, resolvedLevelLabels} = gridModel;
+            const {maxDepth, resolvedLevelLabels} = gridModel;
             if (disabled || !maxDepth || !resolvedLevelLabels) return disabledButton();
 
             const menuItems: MenuItemLike[] = resolvedLevelLabels.map((label, idx) => {
-                const isCurrLevel =
-                    expandLevel === idx ||
-                    (expandLevel > maxDepth && idx === resolvedLevelLabels.length - 1);
+                const isCurrLevel = gridModel.isCurrentExpandLevel(idx);
 
                 return {
                     icon: isCurrLevel ? Icon.check() : Icon.placeholder(),

package/desktop/cmp/filechooser/FileChooser.ts

@@ -12,7 +12,7 @@ import {dropzone} from '@xh/hoist/kit/react-dropzone';
 import {elementFromContent, getLayoutProps} from '@xh/hoist/utils/react';
 import {FileRejection} from 'react-dropzone';
 import {FileChooserModel} from './FileChooserModel';
-import {fromPairs, isEmpty} from 'lodash';
+import {isEmpty} from 'lodash';
 import classNames from 'classnames';
 import {defaultEmptyDisplay} from './impl/DefaultEmptyDisplay';
 import {defaultFileDisplay} from './impl/DefaultFileDisplay';
@@ -88,8 +88,11 @@ export const [FileChooser, fileChooser] = hoistCmp.withFactory<FileChooserProps>
 
         return dropzone({
             ref: model.dropzoneRef,
-            // react-dropzone wants a {type: [extensions]} map; extensions serve as their own keys.
-            accept: accept ? fromPairs(accept.map(ext => [ext, [ext]])) : null,
+            // react-dropzone expects `accept` to be a {type: [extensions]} map. The FileChooserModel
+            // only accepts a list of extensions. Extensions alone are sufficient for validation and
+            // a MIME type is not required. Use `_/_` as a dummy MIME type to prevent console warnings
+            // from react-dropzone.
+            accept: accept ? {'_/_': accept} : null,
             // Disable interaction (drag/click/drop) at the limit; the target shows a clear message.
             disabled: disabled || atLimit,
             maxFiles,

package/desktop/cmp/filechooser/FileChooserModel.ts

@@ -7,7 +7,7 @@
 import {em, li, span, ul, vbox} from '@xh/hoist/cmp/layout';
 import {HoistModel, Some, ToastSpec, XH} from '@xh/hoist/core';
 import '@xh/hoist/desktop/register';
-import {FileRejection} from '@xh/hoist/kit/react-dropzone';
+import {ErrorCode, FileRejection} from '@xh/hoist/kit/react-dropzone';
 import {action, makeObservable, observable} from '@xh/hoist/mobx';
 import {pluralize, withDefault} from '@xh/hoist/utils/js';
 import {createObservableRef} from '@xh/hoist/utils/react';
@@ -187,10 +187,17 @@ export class FileChooserModel extends HoistModel {
         return true;
     }
 
-    private defaultRejectMessage(rejections: FileRejection[]): ReactElement {
-        // 1) Map rejected files to error messages
+    private defaultRejectMessage = (rejections: FileRejection[]): ReactElement => {
+        // 1) Map rejected files to error messages. Use custom message for invalid types to avoid displaying dummy MIME type.
         const errorsByFile = fromPairs(
-            map(rejections, ({file, errors}) => [file.name, map(errors, 'message')])
+            map(rejections, ({file, errors}) => [
+                file.name,
+                map(errors, e =>
+                    e.code === ErrorCode.FileInvalidType
+                        ? `File type must be one of ${this.accept.join(', ')}`
+                        : e.message
+                )
+            ])
         );
 
         // 2) List files with bulleted error messages
@@ -207,7 +214,7 @@ export class FileChooserModel extends HoistModel {
             });
 
         return vbox(rejectItems);
-    }
+    };
 
     private getRejectToastSpec(params: Partial<ToastSpec> | boolean): Partial<ToastSpec> {
         if (params == false) return null;

package/desktop/cmp/filter/FilterChooser.scss

@@ -15,6 +15,47 @@
     margin: 7px 4px;
     align-self: start;
   }
+
+  // Popover mode - collapsed trigger expands into an overlaid popover.
+  &--popover > .bp6-popover-target {
+    display: flex;
+    flex: 1;
+  }
+
+  &__trigger {
+    .xh-select__value-container--is-multi {
+      overflow-y: hidden !important;
+    }
+  }
+
+  // Extra class names required to override the default styles of the popover.
+  &__popover.bp6-popover.bp6-minimal {
+    box-shadow: none;
+
+    // Overlay the expanded input onto the collapsed 30px trigger. Offset follows Blueprint's
+    // resolved placement, which flips (bottom-anchored) near the viewport's bottom edge.
+    &.bp6-popover-placement-bottom {
+      margin-top: -30px !important;
+    }
+    &.bp6-popover-placement-top {
+      margin-bottom: -30px !important;
+    }
+
+    // Content is portaled out of .xh-filter-chooser - restate the flex rule so it fills the width.
+    .bp6-popover-target {
+      display: flex;
+      flex: 1;
+    }
+
+    .bp6-popover-content {
+      background: transparent;
+    }
+
+    .xh-select__value-container--is-multi {
+      height: unset;
+      line-height: unset;
+    }
+  }
 }
 
 .xh-filter-chooser-option {